使用 PyMySQL 连接 TiDB

TiDB 是一个兼容 MySQL 的数据库，PyMySQL 是一个流行的开源 Python 驱动。

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

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

注意

本教程适用于平凯云 Starter , 平凯云 Essential 以及 TiDB 自建集群。

前置条件

完成本教程，你需要：

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

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

（推荐）参照创建一个平凯云 Starter 集群来创建你自己的平凯数据库云服务集群。
参照部署本地测试 TiDB 集群或部署生产环境 TiDB 集群来创建本地集群。

运行示例应用连接 TiDB

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

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

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

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

步骤 2：安装依赖

运行以下命令安装示例应用所需的依赖包（包括 PyMySQL）：

pip install -r requirements.txt

步骤 3：配置连接信息

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

进入 Clusters 页面，点击目标集群名称进入集群概览页面。
点击右上角的 Connect，弹出连接对话框。
确保连接对话框中的配置与你的操作环境一致。
- Connection Type 设置为 Public
- Branch 设置为 main
- Connect With 设置为 General
- Operating System 与你的环境一致
提示：

如果你的程序运行在 Windows Subsystem for Linux (WSL) 中，请切换到对应的 Linux 发行版。
点击 Generate Password 生成一个随机密码。

提示：

如果你之前已经创建过密码，可以继续使用原密码，或者点击 Reset Password 生成新密码。
运行以下命令，将 .env.example 复制并重命名为 .env：
```
cp .env.example .env
```

将对应的连接字符串复制粘贴到 .env 文件中。示例结果如下：

TIDB_HOST='{host}'  # e.g. gateway01.ap-northeast-1.prod.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 文件。

运行以下命令，将 .env.example 复制并重命名为 .env：
```
cp .env.example .env
```
将对应的连接字符串复制粘贴到 .env 文件中。示例结果如下：
```
TIDB_HOST='{tidb_server_host}'
TIDB_PORT='4000'
TIDB_USER='root'
TIDB_PASSWORD='{password}'
TIDB_DB_NAME='test'
```
请务必将 {} 占位符替换为连接参数，并删除 CA_PATH 这一行。如果你在本地运行 TiDB，默认主机地址为 127.0.0.1，密码为空。
保存 .env 文件。

步骤 4：运行代码并检查结果

执行以下命令运行示例代码：
```
python pymysql_example.py
```
检查 Expected-Output.txt 文件，确认输出是否一致。

示例代码片段

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

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

连接 TiDB

from pymysql import Connection
from pymysql.cursors import DictCursor


def get_connection(autocommit: bool = True) -> Connection:
    config = Config()
    db_conf = {
        "host": ${tidb_host},
        "port": ${tidb_port},
        "user": ${tidb_user},
        "password": ${tidb_password},
        "database": ${tidb_db_name},
        "autocommit": autocommit,
        "cursorclass": DictCursor,
    }

    if ${ca_path}:
        db_conf["ssl_verify_cert"] = True
        db_conf["ssl_verify_identity"] = True
        db_conf["ssl_ca"] = ${ca_path}

    return pymysql.connect(**db_conf)

使用该函数时，你需要将 ${tidb_host}、${tidb_port}、${tidb_user}、${tidb_password}、${tidb_db_name} 和 ${ca_path} 替换为你 TiDB 集群的实际值。

插入数据

with get_connection(autocommit=True) as conn:
    with conn.cursor() as cur:
        player = ("1", 1, 1)
        cursor.execute("INSERT INTO players (id, coins, goods) VALUES (%s, %s, %s)", player)

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

查询数据

with get_connection(autocommit=True) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT count(*) FROM players")
        print(cursor.fetchone()["count(*)"])

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

更新数据

with get_connection(autocommit=True) as conn:
    with conn.cursor() as cur:
        player_id, amount, price="1", 10, 500
        cursor.execute(
            "UPDATE players SET goods = goods + %s, coins = coins + %s WHERE id = %s",
            (-amount, price, player_id),
        )

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

删除数据

with get_connection(autocommit=True) as conn:
    with conn.cursor() as cur:
        player_id = "1"
        cursor.execute("DELETE FROM players WHERE id = %s", (player_id,))

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

实用说明

使用驱动还是 ORM 框架？

Python 驱动提供了对数据库的底层访问，但这要求开发者：

手动建立和释放数据库连接。
手动管理数据库事务。
手动将数据行（在 pymysql 中表现为元组或字典）映射为数据对象。

除非你需要编写复杂的 SQL 语句，否则推荐使用 ORM 框架进行开发，例如 SQLAlchemy、Peewee 和 Django ORM。这样可以帮助你：

减少用于管理连接和事务的样板代码。
通过数据对象操作数据，而不是大量 SQL 语句。

后续步骤

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

需要帮助？

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