---
title: "Django 连接 OceanBase 数据库示例程序 - OceanBase 数据库 V4.3.5 | OceanBase 文档中心"
description: Django 连接 OceanBase 数据库示例程序 本文将介绍如何使用 Django 连接 OceanBase 数据库，实现基本的数据库操作，包括创建表、插入数据、更新数据和查询数据等。 前提条件 您已安装 Python 3.x 和 pip。 您已安装 OceanBase 数据库并且创建了 MySQL 模式租户。…
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.3.5 LTS

# Django 连接 OceanBase 数据库示例程序

更新时间：2026-07-15 20:42:45

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.3.5/zh-CN/300.develop/100.application-development-of-mysql-mode/200.sample-program-of-mysql-mode/200.python-of-mysql-mode/500.django-connection-to-oceanbase-database-sample-program.md)  

本文将介绍如何使用 Django 连接 OceanBase 数据库，实现基本的数据库操作，包括创建表、插入数据、更新数据和查询数据等。

## 前提条件

- 您已安装 Python 3.x 和 pip。
 - 您已安装 OceanBase 数据库并且创建了 MySQL 模式租户。

## 操作步骤

1. 获取 OceanBase 数据库连接串。
 2. 安装 Django 和 MySQL 客户端库。
 3. 创建 Django 项目和应用。
 4. 配置数据库连接。
 5. 创建模型。
 6. 运行迁移。
 7. 编写视图和 URL 配置。
 8. 运行开发服务器。

### 步骤一：获取 OceanBase 数据库连接串

联系 OceanBase 数据库部署人员或者管理员获取相应的数据库连接串。

```shell
obclient -h$host -P$port -u$user_name -p$password -D$database_name

```

**参数说明：**

- `$host`：提供 OceanBase 数据库连接 IP。OceanBase 数据库代理（OceanBase Database Proxy，ODP）连接方式使用的是一个 ODP 地址；直连方式使用的是 OBServer 节点的 IP 地址。
 - `$port`：提供 OceanBase 数据库连接端口。ODP 连接的方式默认是 `2883`，在部署 ODP 时可自定义；直连方式默认是 `2881`，在部署 OceanBase 数据库时可自定义。
 - `$database_name`：需要访问的数据库名称。

  #### 注意

  连接租户的用户需要拥有该数据库的 `CREATE`、`INSERT`、`UPDATE` 和 `SELECT` 权限。更多有关用户权限的信息，请参见 [MySQL 模式下的权限分类](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002016100)。
 - `$user_name`：提供租户的连接账户。ODP 连接的常用格式：`用户名@租户名#集群名` 或者 `集群名:租户名:用户名`；直连方式格式：`用户名@租户名`。
 - `$password`：提供账户密码。

更多连接串的信息，请参见 [通过 OBClient 连接 OceanBase 租户](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013251)。

**示例如下：**

```shell
obclient -hxxx.xxx.xxx.xxx -P2881 -utest_user001@mysql001 -p****** -Dtest

```

### 步骤二：安装 Django 和 MySQL 客户端库

Django 是一个高级 Python Web 框架，它提供了 ORM（对象关系映射）系统，可以简化数据库操作。Django 支持多种数据库后端，包括 MySQL、PostgreSQL、SQLite 等。

打开命令提示符或 PowerShell 终端，运行以下命令，安装 Django 和 MySQL 客户端库。

```shell
pip install django mysqlclient

```

安装完成后，可以通过以下命令验证安装是否成功：

```shell
pip list | grep -i django

```

#### 说明

Django 是一个功能强大的 Web 框架，它提供了 ORM 系统，可以简化数据库操作。Django 的 ORM 系统支持多种数据库后端，包括 MySQL、PostgreSQL、SQLite 等。

### 步骤三：创建 Django 项目和应用

1. 创建一个名为 `oceanbase_demo` 的 Django 项目。

   ```shell
   django-admin startproject oceanbase_demo

   ```
 2. 进入项目目录。

   ```shell
   cd oceanbase_demo

   ```
 3. 创建一个名为 `users` 的应用。

   ```shell
   python manage.py startapp users

   ```

### 步骤四：配置数据库连接

1. 打开 `oceanbase_demo/settings.py` 文件，修改数据库配置。

   ```python
   DATABASES = {
       'default': {
           'ENGINE': 'django.db.backends.mysql',
           'NAME': 'test',
           'USER': 'test_user001@mysql001',
           'PASSWORD': '******',
           'HOST': 'xxx.xxx.xxx.xxx',
           'PORT': '2881',
           'OPTIONS': {
               'charset': 'utf8mb4',
           },
       }
   }

   ```
 2. 在 `INSTALLED_APPS` 中添加 `users` 应用。

   ```python
   INSTALLED_APPS = [
       'django.contrib.admin',
       'django.contrib.auth',
       'django.contrib.contenttypes',
       'django.contrib.sessions',
       'django.contrib.messages',
       'django.contrib.staticfiles',
       'users',
   ]

   ```

### 步骤五：创建模型

1. 打开 `users/models.py` 文件，创建 `User` 模型。

   ```python
   from django.db import models

   class User(models.Model):
       name = models.CharField(max_length=50)
       age = models.IntegerField()

       def __str__(self):
           return f"{self.name} ({self.age})"

   ```

### 步骤六：运行迁移

1. 创建迁移文件。

   ```shell
   python manage.py makemigrations

   ```
 2. 应用迁移。

   ```shell
   python manage.py migrate

   ```

### 步骤七：编写视图和 URL 配置

1. 打开 `users/views.py` 文件，创建视图函数。

   ```python
   from django.shortcuts import render
   from django.http import HttpResponse
   from .models import User

   def index(request):
       # 插入数据
       User.objects.create(name='John', age=20)
       User.objects.create(name='Lucy', age=25)
       User.objects.create(name='Tom', age=30)

       # 更新数据
       user = User.objects.get(name='Lucy')
       user.age = 26
       user.save()

       # 查询数据
       users = User.objects.all()
       result = "<h1>Users</h1><ul>"
       for user in users:
           result += f"<li>{user}</li>"
       result += "</ul>"

       return HttpResponse(result)

   ```
 2. 打开 `oceanbase_demo/urls.py` 文件，配置 URL。

   ```python
   from django.contrib import admin
   from django.urls import path
   from users import views

   urlpatterns = [
       path('admin/', admin.site.urls),
       path('', views.index, name='index'),
   ]

   ```

### 步骤八：运行开发服务器

1. 运行开发服务器。

   ```shell
   python manage.py runserver

   ```
 2. 在浏览器中访问 `http://127.0.0.1:8000/`，查看结果。

   返回结果如下：

   ```html
   <h1>Users</h1>
   <ul>
       <li>John (20)</li>
       <li>Lucy (26)</li>
       <li>Tom (30)</li>
   </ul>

   ```

## 错误处理

在使用 Django 连接 OceanBase 数据库时，可能会遇到各种错误。以下是一些常见的错误及其处理方法：

1. **连接错误**：如果无法连接到数据库，请检查连接参数是否正确，包括主机名、端口、用户名、密码和数据库名。
 2. **权限错误**：如果遇到权限相关的错误，请确保用户拥有足够的权限来执行所需的操作。
 3. **SQL 语法错误**：如果 SQL 语句有语法错误，请检查 SQL 语句的语法是否正确。
 4. **数据类型错误**：如果插入的数据类型与表定义不匹配，请确保插入的数据类型正确。

在 Django 中，我们可以使用 `try-except` 语句来捕获和处理这些错误，确保程序在遇到错误时能够优雅地处理，而不是直接崩溃。同时，我们可以使用 Django 的日志系统记录错误信息，方便调试和问题排查。

## 相关文档

- 更多连接 OceanBase 数据库的信息，请参见 [连接方式概述](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002013253)。
 - 更多创建数据库的信息，请参见 [CREATE DATABASE](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000002017062)。

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线