使用 Django 连接到 TiDB
TiDB 是一个兼容 MySQL 的数据库。Django 为当前流行的 Python Web 框架之一,它内部实现了一个强大的 ORM (Object Relational Mapper) 系统。
本文档将展示如何使用 TiDB 和 Django 来完成以下任务:
- 配置你的环境。
- 使用 Django 连接到 TiDB 集群。
- 构建并运行你的应用程序。你也可以参考示例代码片段,完成基本的 CRUD 操作。
前置需求
- 推荐 Python 3.8 及以上版本。
- Git。
- TiDB 集群。如果你还没有 TiDB 集群,可以按照以下方式创建:
- (推荐方式)参考创建 TiDB Serverless 集群,创建你自己的 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.0,<4.3.0
,其中 minor 版本号不需要完全相同。建议使用最新的 minor 版本。
更多信息,请参考 django-tidb 仓库。
第 3 步:配置连接信息
根据不同的 TiDB 部署方式,使用不同的方法连接到 TiDB 集群。
- TiDB Serverless
- TiDB Dedicated
- 本地部署 TiDB
在 TiDB Cloud 的 Clusters 页面中,选择你的 TiDB Serverless 集群,进入集群的 Overview 页面。
点击右上角的 Connect 按钮,将会弹出连接对话框。
确认对话框中的配置和你的运行环境一致。
- Connection Type 为
Public
。 - Branch 选择
main
。 - Connect With 选择
General
。 - Operating System 为你的运行环境。
- Connection Type 为
如果你还没有设置密码,点击 Generate Password 生成一个随机密码。
运行以下命令,将
.env.example
复制并重命名为.env
:cp .env.example .env复制并粘贴对应连接字符串至
.env
中。示例结果如下:TIDB_HOST='{host}' # e.g. xxxxxx.aws.tidbcloud.com TIDB_PORT='4000' TIDB_USER='{user}' # e.g. xxxxxx.root TIDB_PASSWORD='{password}' TIDB_DB_NAME='test' CA_PATH='{ssl_ca}' # e.g. /etc/ssl/certs/ca-certificates.crt (Debian / Ubuntu / Arch)注意替换
{}
中的占位符为连接对话框中获得的值。保存
.env
文件。
在 TiDB Cloud 的 Clusters 页面中,选择你的 TiDB Dedicated 集群,进入集群的 Overview 页面。
点击右上角的 Connect 按钮,将会出现连接对话框。
在连接对话框中,从 Connection Type 下拉列表中选择 Public,并点击 CA cert 下载 CA 文件。
如果你尚未配置 IP 访问列表,请在首次连接前点击 Configure IP Access List 或按照配置 IP 访问列表(英文)中的步骤进行配置。
除 Public 连接类型外,TiDB Dedicated 还支持 Private Endpoint 和 VPC Peering 连接类型。详情请参阅连接 TiDB Dedicated 集群(英文)。
运行以下命令,将
.env.example
复制并重命名为.env
:cp .env.example .env复制并粘贴对应的连接字符串至
.env
中。示例结果如下:TIDB_HOST='{host}' # e.g. xxxxxx.aws.tidbcloud.com TIDB_PORT='4000' TIDB_USER='{user}' # e.g. xxxxxx.root TIDB_PASSWORD='{password}' TIDB_DB_NAME='test' CA_PATH='{your-downloaded-ca-path}'注意替换
{}
中的占位符为连接对话框中获得的值,并配置前面步骤中下载好的证书路径。保存
.env
文件。
运行以下命令,将
.env.example
复制并重命名为.env
:cp .env.example .env复制并粘贴对应 TiDB 的连接字符串至
.env
中。示例结果如下:TIDB_HOST='{host}' TIDB_PORT='4000' TIDB_USER='root' TIDB_PASSWORD='{password}' TIDB_DB_NAME='test'注意替换
{}
中的占位符为你的 TiDB 对应的值,并删除CA_PATH
这行。如果你在本机运行 TiDB,默认 Host 地址为127.0.0.1
,密码为空。保存
.env
文件。
第 4 步:初始化数据库
在示例项目根目录执行以下命令,初始化数据库:
python manage.py migrate
Operations to perform:
Apply all migrations: admin, auth, contenttypes, sample_project, sessions
Running migrations:
Applying contenttypes.0001_initial... OK
Applying auth.0001_initial... OK
Applying admin.0001_initial... OK
Applying admin.0002_logentry_remove_auto_add... OK
Applying admin.0003_logentry_add_action_flag_choices... OK
Applying contenttypes.0002_remove_content_type_name... OK
Applying auth.0002_alter_permission_name_max_length... OK
Applying auth.0003_alter_user_email_max_length... OK
Applying auth.0004_alter_user_username_opts... OK
Applying auth.0005_alter_user_last_login_null... OK
Applying auth.0006_require_contenttypes_0002... OK
Applying auth.0007_alter_validators_add_error_messages... OK
Applying auth.0008_alter_user_username_max_length... OK
Applying auth.0009_alter_user_last_name_max_length... OK
Applying auth.0010_alter_group_name_max_length... OK
Applying auth.0011_update_proxy_permissions... OK
Applying auth.0012_alter_user_first_name_max_length... OK
Applying sample_project.0001_initial... OK
Applying sessions.0001_initial... OK
第 5 步:运行示例应用程序
在开发模式下运行示例应用程序:
python manage.py runserver应用程序默认在
8000
端口上运行。如果你想要使用其他端口号,可以在命令后添加端口号,例如:python manage.py runserver 8080打开浏览器,在地址栏输入
http://localhost:8000/
,访问示例应用程序,你可以进行以下操作:- 创建一个新的 Player
- 批量创建 Player
- 查看所有的 Player
- 更新 Player
- 删除 Player
- 在两个 Player 之间交易物品
示例代码片段
你可参考以下关键代码片段,完成自己的应用开发。
完整代码及其运行方式,见代码仓库 tidb-samples/tidb-python-django-quickstart。
配置数据库连接
打开 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 模型。
插入数据
# 插入单个对象
player = Player.objects.create(name="player1", coins=100, goods=1)
# 批量插入多个对象
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),
])
更多信息参考插入数据。
查询数据
# 查询单个对象
player = Player.objects.get(name="player1")
# 查询多个对象
filtered_players = Player.objects.filter(name="player1")
# 查询所有对象
all_players = Player.objects.all()
更多信息参考查询数据。
更新数据
# 更新单个对象
player = Player.objects.get(name="player1")
player.coins = 200
player.save()
# 批量更新多个对象
Player.objects.filter(coins=100).update(coins=200)
更多信息参考更新数据。
删除数据
# 删除单个对象
player = Player.objects.get(name="player1")
player.delete()
# 批量删除多个对象
Player.objects.filter(coins=100).delete()
更多信息参考删除数据。
下一步
- 关于 Django 的更多使用方法,可以参考 Django 官方文档。
- 你可以继续阅读开发者文档,以获取更多关于 TiDB 应用开发的最佳实践。例如:插入数据、更新数据、删除数据、单表读取、事务、SQL 性能优化等。
- 如果你更倾向于参与课程进行学习,我们也提供专业的 TiDB 开发者课程支持,并在考试后提供相应的资格认证。
需要帮助?
如果在开发的过程中遇到问题,可以在 AskTUG 上进行提问,寻求帮助。