使用 mysqlclient 连接 TiDB

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

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

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

前置条件

完成本教程，你需要：

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

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

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

运行示例应用连接 TiDB

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

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

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

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

第 2 步：安装依赖

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

pip install -r requirements.txt

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

第 3 步：配置连接信息

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

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

1. 执行以下命令运行示例代码：

   python mysqlclient_example.py
   

2. 检查 Expected-Output.txt 是否与输出结果一致。

代码示例片段

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

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

连接 TiDB

def get_mysqlclient_connection(autocommit:bool=True) -> MySQLdb.Connection:
    db_conf = {
        "host": ${tidb_host},
        "port": ${tidb_port},
        "user": ${tidb_user},
        "password": ${tidb_password},
        "database": ${tidb_db_name},
        "autocommit": autocommit
    }

    if ${ca_path}:
        db_conf["ssl_mode"] = "VERIFY_IDENTITY"
        db_conf["ssl"] = {"ca": ${ca_path}}

    return MySQLdb.connect(**db_conf)

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

插入数据

with get_mysqlclient_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_mysqlclient_connection(autocommit=True) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT count(*) FROM players")
        print(cur.fetchone()[0])

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

更新数据

with get_mysqlclient_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_mysqlclient_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 驱动提供了对数据库的底层访问，但这要求开发者：

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

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

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

后续步骤

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

需要帮助？

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