使用 Django 连接 TiDB

TiDB 是一个兼容 MySQL 的数据库，Django 是一个流行的 Python Web 框架，内置了强大的对象关系映射（ORM）库。

在本教程中，你可以学习如何使用 TiDB 和 Django 完成以下任务：

• 搭建你的开发环境。
• 使用 Django 连接到你的 TiDB 集群。
• 构建并运行你的应用程序。你还可以找到基本 CRUD 操作的示例代码片段。

前置条件

完成本教程，你需要：

• Python 3.8 或更高版本。
• Git。
• 一个 TiDB 集群。

如果你还没有 TiDB 集群，可以按如下方式创建：

• （推荐）参照创建 TiDB Cloud Starter 集群 创建你自己的 TiDB Cloud 集群。
• 参照部署本地测试 TiDB 集群 或部署生产环境 TiDB 集群 创建本地集群。

运行示例应用连接 TiDB

本节演示如何运行示例应用代码并连接到 TiDB。

步骤 1：克隆示例应用仓库

在终端窗口中运行以下命令，克隆示例代码仓库：

git clone https://github.com/tidb-samples/tidb-python-django-quickstart.git
cd tidb-python-django-quickstart

步骤 2：安装依赖

运行以下命令安装示例应用所需的依赖包（包括 Django、django-tidb 和 mysqlclient）：

pip install -r requirements.txt

如果你在安装 mysqlclient 时遇到问题，请参考 mysqlclient 官方文档。

什么是 django-tidb？

django-tidb 是 Django 的 TiDB 方言，用于解决 TiDB 与 Django 之间的兼容性问题。

安装 django-tidb 时，请选择与你的 Django 版本相匹配的版本。例如，如果你使用的是 django==4.2.*，则安装 django-tidb==4.2.*。小版本号无需完全一致，建议使用最新的小版本。

更多信息请参考 django-tidb 仓库。

步骤 3：配置连接信息

根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。

步骤 4：初始化数据库

在项目根目录下运行以下命令，初始化数据库：

python manage.py migrate

步骤 5：运行示例应用

1. 以开发模式运行应用：

   python manage.py runserver
   

   应用默认运行在端口 8000。如需使用其他端口，可在命令后追加端口号。例如：

   python manage.py runserver 8080
   

2. 访问应用，在浏览器中打开 http://localhost:8000/。在示例应用中，你可以：

   • 创建新玩家
   • 批量创建玩家
   • 查看所有玩家
   • 更新玩家信息
   • 删除玩家
   • 在两个玩家之间交易物品

示例代码片段

你可以参考以下示例代码片段，完成你自己的应用开发。

完整示例代码及运行方法请参见 tidb-samples/tidb-python-django-quickstart 仓库。

连接 TiDB

在 sample_project/settings.py 文件中，添加如下配置：

DATABASES = {
    "default": {
        "ENGINE": "django_tidb",
        "HOST": ${tidb_host},
        "PORT": ${tidb_port},
        "USER": ${tidb_user},
        "PASSWORD": ${tidb_password},
        "NAME": ${tidb_db_name},
        "OPTIONS": {
            "charset": "utf8mb4",
        },
    }
}

TIDB_CA_PATH = ${ca_path}
if TIDB_CA_PATH:
    DATABASES["default"]["OPTIONS"]["ssl_mode"] = "VERIFY_IDENTITY"
    DATABASES["default"]["OPTIONS"]["ssl"] = {
        "ca": TIDB_CA_PATH,
    }

你需要将 ${tidb_host}、${tidb_port}、${tidb_user}、${tidb_password}、${tidb_db_name} 和 ${ca_path} 替换为你的 TiDB 集群的实际值。

定义数据模型

from django.db import models

class Player(models.Model):
    name = models.CharField(max_length=32, blank=False, null=False)
    coins = models.IntegerField(default=100)
    goods = models.IntegerField(default=1)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

更多信息请参考 Django models。

插入数据

# insert a single object
player = Player.objects.create(name="player1", coins=100, goods=1)

# bulk insert multiple objects
Player.objects.bulk_create([
    Player(name="player1", coins=100, goods=1),
    Player(name="player2", coins=200, goods=2),
    Player(name="player3", coins=300, goods=3),
])

更多信息请参考 插入数据。

查询数据

# get a single object
player = Player.objects.get(name="player1")

# get multiple objects
filtered_players = Player.objects.filter(name="player1")

# get all objects
all_players = Player.objects.all()

更多信息请参考 查询数据。

更新数据

# update a single object
player = Player.objects.get(name="player1")
player.coins = 200
player.save()

# update multiple objects
Player.objects.filter(coins=100).update(coins=200)

更多信息请参考 更新数据。

删除数据

# delete a single object
player = Player.objects.get(name="player1")
player.delete()

# delete multiple objects
Player.objects.filter(coins=100).delete()

更多信息请参考 删除数据。

后续步骤

• 通过 Django 官方文档 学习更多 Django 的用法。
• 通过 开发者指南 各章节，学习 TiDB 应用开发最佳实践，例如 插入数据、更新数据、删除数据、单表读取、事务 以及 SQL 性能优化。
• 通过专业的 TiDB 开发者课程，并在通过考试后获得 TiDB 认证。

需要帮助？

在 Discord 或 Slack 社区提问，或提交支持工单。