Django 连接 OceanBase 数据库示例程序

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

编辑

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

前提条件

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

操作步骤

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

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

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

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 模式下的权限分类。
$user_name：提供租户的连接账户。ODP 连接的常用格式：用户名@租户名#集群名 或者 集群名:租户名:用户名；直连方式格式：用户名@租户名。
$password：提供账户密码。

更多连接串的信息，请参见通过 OBClient 连接 OceanBase 租户。

示例如下：

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

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

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

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

pip install django mysqlclient

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

pip list | grep -i django

说明

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

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

创建一个名为 oceanbase_demo 的 Django 项目。
```
django-admin startproject oceanbase_demo
```
进入项目目录。
```
cd oceanbase_demo
```
创建一个名为 users 的应用。
```
python manage.py startapp users
```

步骤四：配置数据库连接

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

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

在 INSTALLED_APPS 中添加 users 应用。

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

步骤五：创建模型

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

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})"

步骤六：运行迁移

创建迁移文件。
```
python manage.py makemigrations
```
应用迁移。
```
python manage.py migrate
```

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

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

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)

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

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'),
]

步骤八：运行开发服务器

运行开发服务器。
```
python manage.py runserver
```

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

返回结果如下：

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

错误处理

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

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

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