From faa6ce9db46e290cb8022aab13c8fab797490cbc Mon Sep 17 00:00:00 2001 From: Ti Chi Robot Date: Thu, 31 Aug 2023 16:36:39 +0800 Subject: [PATCH] develop: improve python mysqlclient sample code doc (#14902) (#14941) --- ...e-sample-application-python-mysqlclient.md | 149 +++++++++++------- 1 file changed, 92 insertions(+), 57 deletions(-) diff --git a/develop/dev-guide-sample-application-python-mysqlclient.md b/develop/dev-guide-sample-application-python-mysqlclient.md index 7504b8a7e8f8..0e533098ca14 100644 --- a/develop/dev-guide-sample-application-python-mysqlclient.md +++ b/develop/dev-guide-sample-application-python-mysqlclient.md @@ -1,21 +1,25 @@ --- title: 使用 mysqlclient 连接到 TiDB -summary: 本文描述了 TiDB 和 mysqlclient 的连接步骤，并给出了简单示例代码片段。 +summary: 了解如何使用 mysqlclient 连接到 TiDB。本文提供了使用 mysqlclient 与 TiDB 交互的 Python 示例代码片段。 --- - - +# 使用 mysqlclient 连接到 TiDB -# 如何用 mysqlclient 连接到 TiDB +TiDB 是一个兼容 MySQL 的数据库。[mysqlclient](https://github.com/PyMySQL/mysqlclient) 为当前流行的开源 Python Driver 之一。 -TiDB 是一个兼容 MySQL 的数据库。[mysqlclient](https://pypi.org/project/mysqlclient/) 为当前流行的开源 Python Driver 之一。 +本文档将展示如何使用 TiDB 和 mysqlclient 来完成以下任务： -本文档将展示如何使用 TiDB 和 mysqlclient 来构造一个简单的 CRUD 应用程序。 +- 配置你的环境。 +- 使用 mysqlclient 连接到 TiDB 集群。 +- 构建并运行你的应用程序。你也可以参考[示例代码片段](#示例代码片段)，完成基本的 CRUD 操作。 + +> **注意** +> +> 本文档适用于 TiDB Serverless、TiDB Dedicated 和本地部署的 TiDB。 ## 前置需求 - 推荐 [Python **3.10**](https://www.python.org/downloads/) 及以上版本。 -- mysqlclient **2.1.1** 版本。在运行本教程的过程中会进行安装和配置，如果遇到安装问题，请参考 [mysqlclient 官方文档](https://github.com/PyMySQL/mysqlclient#install)。 - [Git](https://git-scm.com/downloads)。 - TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建： - （推荐方式）参考[创建 TiDB Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-serverless-集群)，创建你自己的 TiDB Cloud 集群。 @@ -27,17 +31,23 @@ TiDB 是一个兼容 MySQL 的数据库。[mysqlclient](https://pypi.org/project ### 第 1 步：克隆示例代码仓库到本地 +运行以下命令，将示例代码仓库克隆到本地： + ```bash -git clone https://github.com/pingcap-inc/tidb-example-python.git +git clone https://github.com/tidb-samples/tidb-python-mysqlclient-quickstart.git +cd tidb-python-mysqlclient-quickstart ``` -### 第 2 步：安装依赖 (包括 mysqlclient) +### 第 2 步：安装依赖 + +运行以下命令，安装示例代码所需要的依赖（包括 mysqlclient）： ```bash -cd tidb-example-python; -pip install -r requirement.txt +pip install -r requirements.txt ``` +如果遇到安装问题，请参考 [mysqlclient 官方文档](https://github.com/PyMySQL/mysqlclient#install)。 + ### 第 3 步：配置连接信息 根据不同的 TiDB 部署方式，使用不同的方法连接到 TiDB 集群。 @@ -46,79 +56,85 @@ pip install -r requirement.txt
-1. 在 TiDB Cloud Web Console 中，选择你的 TiDB Serverless 集群，进入 **Overview** 页面，点击右上角的 **Connect** 按钮。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Serverless 集群，进入集群的 **Overview** 页面。 -2. 确认窗口中的配置和你的运行环境一致。 +2. 点击右上角的 **Connect** 按钮，将会弹出连接对话框。 - - Endpoint 为 **Public** - - Connect With 选择 **General** - - Operating System 为你的运行环境。 +3. 确认对话框中的配置和你的运行环境一致。 - 如果你在 Windows Subsystem for Linux (WSL) 中运行，请切换为对应的 Linux 发行版。 + - **Endpoint Type** 为 `Public`。 + - **Connect With** 选择 `General`。 + - **Operating System** 为你的运行环境。 -3. 点击 **Generate Password** 生成密码。 - - 如果你之前已经生成过密码，可以直接使用原密码，或点击 **Reset Password** 重新生成密码。 + > **Tip:** + > + > 如果你在 Windows Subsystem for Linux (WSL) 中运行，请切换为对应的 Linux 发行版。 -4. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： +4. 如果你还没有设置密码，点击 **Create password** 生成一个随机密码。 + + > **Tip:** + > + > 如果你之前已经生成过密码，可以直接使用原密码，或点击 **Reset password** 重新生成密码。 + +5. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```bash cp .env.example .env ``` -5. 复制并粘贴对应连接字符串至 `.env` 中。示例结果如下。 +6. 复制并粘贴对应连接字符串至 `.env` 中。示例结果如下： - ```python - TIDB_HOST='{gateway-region}.aws.tidbcloud.com' + ```dotenv + TIDB_HOST='{host}' # e.g. gateway01.ap-northeast-1.prod.aws.tidbcloud.com TIDB_PORT='4000' - TIDB_USER='{prefix}.root' + TIDB_USER='{user}' # e.g. xxxxxx.root TIDB_PASSWORD='{password}' TIDB_DB_NAME='test' CA_PATH='' ``` - 注意替换 `{}` 中的占位符为 **Connect** 窗口中获得的值。 - - TiDB Serverless 要求使用 secure connection，由于 mysqlclient 的 `ssl_mode` 默认为 `PREFERRED`，所以不需要你手动指定 `CA_PATH`，设置为空即可。但如果你有特殊原因需要手动指定 `CA_PATH`，可以参考 [TiDB Cloud 文档](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters#root-certificate-default-path)获取不同操作系统下证书的路径。 + 注意替换 `{}` 中的占位符为连接对话框中获得的值。 + + TiDB Serverless 要求使用 TLS (SSL) connection，由于 mysqlclient 的 `ssl_mode` 默认为 `PREFERRED`，所以不需要你手动指定 `CA_PATH`，设置为空即可。但如果你有特殊原因需要手动指定 `CA_PATH`，可以参考 [TiDB Cloud 文档](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters#root-certificate-default-path)获取不同操作系统下证书的路径。 -6. 保存文件。 +7. 保存 `.env` 文件。
-1. 在 TiDB Cloud Web Console 中，选择你的 TiDB Dedicated 集群，进入 **Overview** 页面，点击右上角的 **Connect** 按钮。点击 **Allow Access from Anywhere** 并点击 **Download TiDB cluster CA** 下载证书。 +1. 在 TiDB Cloud 的 [**Clusters**](https://tidbcloud.com/console/clusters) 页面中，选择你的 TiDB Dedicated 集群，进入集群的 **Overview** 页面。 - +2. 点击右上角的 **Connect** 按钮，将会出现连接对话框。 - 更多配置细节，可参考 [TiDB Dedicated 标准连接教程](https://docs.pingcap.com/tidbcloud/connect-via-standard-connection)。 +3. 在对话框中点击 **Allow Access from Anywhere**，然后点击 **Download TiDB cluster CA** 下载 TiDB Cloud 提供的 CA 证书。 - + 更多配置细节，可参考 [TiDB Dedicated 标准连接教程（英文）](https://docs.pingcap.com/tidbcloud/connect-via-standard-connection)。 -2. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： +4. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： ```bash cp .env.example .env ``` -3. 复制并粘贴对应的连接字符串至 `.env` 中。示例结果如下： +5. 复制并粘贴对应的连接字符串至 `.env` 中。示例结果如下： - ```python - TIDB_HOST='{host}.clusters.tidb-cloud.com' + ```dotenv + TIDB_HOST='{host}' # e.g. tidb.xxxx.clusters.tidb-cloud.com TIDB_PORT='4000' - TIDB_USER='{username}' + TIDB_USER='{user}' # e.g. root TIDB_PASSWORD='{password}' TIDB_DB_NAME='test' CA_PATH='{your-downloaded-ca-path}' ``` - 注意替换 `{}` 中的占位符为 **Connect** 窗口中获得的值，并配置前面步骤中下载好的证书路径。 + 注意替换 `{}` 中的占位符为连接对话框中获得的值，并配置前面步骤中下载好的证书路径。 -4. 保存文件。 +6. 保存 `.env` 文件。
-
+
1. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： @@ -126,10 +142,10 @@ pip install -r requirement.txt cp .env.example .env ``` -2. 复制并粘贴对应 TiDB 的连接字符串至 `.env` 中。示例结果如下。 +2. 复制并粘贴对应 TiDB 的连接字符串至 `.env` 中。示例结果如下： - ```python - TIDB_HOST='{tidb_server_host}' + ```dotenv + TIDB_HOST='{host}' TIDB_PORT='4000' TIDB_USER='root' TIDB_PASSWORD='{password}' @@ -138,7 +154,7 @@ pip install -r requirement.txt 注意替换 `{}` 中的占位符为你的 TiDB 对应的值，并删除 `CA_PATH` 这行。如果你在本机运行 TiDB，默认 Host 地址为 `127.0.0.1`，密码为空。 -3. 保存文件。 +3. 保存 `.env` 文件。
@@ -148,16 +164,18 @@ pip install -r requirement.txt 1. 运行下述命令，执行示例代码： - ```python - python3 mysqlclient_example.py + ```bash + python mysqlclient_example.py ``` -2. 查看[示例输出](https://github.com/pingcap-inc/tidb-example-python/blob/main/Expected-Output.md#mysqlclient)，并与你的程序输出进行比较。结果近似即为连接成功。 +2. 查看 [`Expected-Output.txt`](https://github.com/tidb-samples/tidb-python-mysqlclient-quickstart/blob/main/Expected-Output.txt)，并与你的程序输出进行比较。结果近似即为连接成功。 -## 重点代码片段 +## 示例代码片段 你可参考以下关键代码片段，完成自己的应用开发。 +完整代码及其运行方式，见代码仓库 [tidb-samples/tidb-python-mysqlclient-quickstart](https://github.com/tidb-samples/tidb-python-mysqlclient-quickstart)。 + ### 连接到 TiDB ```python @@ -186,7 +204,7 @@ def get_mysqlclient_connection(autocommit:bool=True) -> MySQLdb.Connection: with get_mysqlclient_connection(autocommit=True) as conn: with conn.cursor() as cur: player = ("1", 1, 1) - cursor.execute("INSERT INTO player (id, coins, goods) VALUES (%s, %s, %s)", player) + cursor.execute("INSERT INTO players (id, coins, goods) VALUES (%s, %s, %s)", player) ``` 更多信息参考[插入数据](/develop/dev-guide-insert-data.md)。 @@ -196,7 +214,7 @@ with get_mysqlclient_connection(autocommit=True) as conn: ```python with get_mysqlclient_connection(autocommit=True) as conn: with conn.cursor() as cur: - cur.execute("SELECT count(*) FROM player") + cur.execute("SELECT count(*) FROM players") print(cur.fetchone()[0]) ``` @@ -208,7 +226,10 @@ with get_mysqlclient_connection(autocommit=True) as conn: with get_mysqlclient_connection(autocommit=True) as conn: with conn.cursor() as cur: player_id, amount, price="1", 10, 500 - cursor.execute("UPDATE player SET goods = goods + %s, coins = coins + %s WHERE id = %s", (-amount, price, player_id)) + cursor.execute( + "UPDATE players SET goods = goods + %s, coins = coins + %s WHERE id = %s", + (-amount, price, player_id), + ) ``` 更多信息参考[更新数据](/develop/dev-guide-update-data.md)。 @@ -219,18 +240,32 @@ with get_mysqlclient_connection(autocommit=True) as conn: with get_mysqlclient_connection(autocommit=True) as conn: with conn.cursor() as cur: player_id = "1" - cursor.execute("DELETE FROM player WHERE id = %s", (player_id,)) + cursor.execute("DELETE FROM players WHERE id = %s", (player_id,)) ``` 更多信息参考[删除数据](/develop/dev-guide-delete-data.md)。 ## 注意事项 -- 完整代码及其运行方式，见 [tidb-example-python](https://github.com/pingcap-inc/tidb-example-python/blob/main/README-zh.md) GitHub 仓库。 -- Driver 封装程度较低，因此在程序内会见到大量的 SQL 语句。与 ORM 不同，因为没有数据对象的存在，`mysqlclient` 的查询对象以元组 (tuple) 进行表示。虽然 Python 的 Driver 相较其他语言的使用更方便，但因其不可屏蔽底层实现，需手动管控事务的特性，如果没有大量必须使用 SQL 的场景，仍然推荐使用 ORM 进行程序编写。这可以降低程序的耦合性。 -- 关于 mysqlclient 的更多使用方法，可以参考 [mysqlclient 官方文档](https://mysqlclient.readthedocs.io/)。 +### 使用驱动程序还是 ORM 框架？ + +Python 驱动程序提供对数据库的底层访问，但要求开发者： + +- 手动建立和释放数据库连接 +- 手动管理数据库事务 +- 手动将数据行（在 mysqlclient 中表示为元组 (tuple)）映射为数据对象 + +建议仅在需要编写复杂的 SQL 语句时使用驱动程序。其他情况下，建议使用 [ORM](https://zh.wikipedia.org/wiki/对象关系映射) 框架进行开发，例如 [SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md)、[Peewee](/develop/dev-guide-sample-application-python-peewee.md) 和 Django。ORM 可以帮助你： + +- 减少管理连接和事务的[模板代码](https://en.wikipedia.org/wiki/Boilerplate_code) +- 使用数据对象代替大量 SQL 语句来操作数据 ## 下一步 -- 你可以继续阅读开发者文档，以获取更多关于 TiDB 的开发者知识。例如：[插入数据](/develop/dev-guide-insert-data.md)，[更新数据](/develop/dev-guide-update-data.md)，[删除数据](/develop/dev-guide-delete-data.md)，[单表读取](/develop/dev-guide-get-data-from-single-table.md)，[事务](/develop/dev-guide-transaction-overview.md)，[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 +- 关于 mysqlclient 的更多使用方法，可以参考 [mysqlclient 官方文档](https://mysqlclient.readthedocs.io/)。 +- 你可以继续阅读开发者文档，以获取更多关于 TiDB 应用开发的最佳实践。例如：[插入数据](/develop/dev-guide-insert-data.md)、[更新数据](/develop/dev-guide-update-data.md)、[删除数据](/develop/dev-guide-delete-data.md)、[单表读取](/develop/dev-guide-get-data-from-single-table.md)、[事务](/develop/dev-guide-transaction-overview.md)、[SQL 性能优化](/develop/dev-guide-optimize-sql-overview.md)等。 - 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 + +## 需要帮助? + +如果在开发的过程中遇到问题，可以在 [AskTUG](https://asktug.com/?utm_source=docs-cn-dev-guide) 上进行提问，寻求帮助。