pingcap-inc · Icemap · Jul 28, 2023 · Jul 28, 2023 · Jul 28, 2023 · Jul 28, 2023
diff --git a/.env.example b/.env.example
@@ -0,0 +1,6 @@
+TIDB_HOST='xxxxxxxx.aws.tidbcloud.com'
+TIDB_PORT='4000'
+TIDB_USER='xxxxxxxxxxx.root'
+TIDB_PASSWORD='xxxxxxx'
+TIDB_DB_NAME='test'
+CA_PATH='/etc/ssl/cert.pem'
diff --git a/Makefile b/Makefile
@@ -26,28 +26,20 @@ test:
 dep:
 	pip3 install -r requirement.txt
 
-recreate-table:
-	mycli --host 127.0.0.1 --port 4000 -u root --no-warn < player_init.sql
-
 # ORMs
 peewee-test:
-	make recreate-table
 	python3 peewee_example.py
 
 sqlalchemy-test:
-	make recreate-table
 	python3 sqlalchemy_example.py
 
 # Drivers
 mysqlclient-test:
-	make recreate-table
 	python3 mysqlclient_example.py
 
 pymysql-test:
-	make recreate-table
 	python3 pymysql_example.py
 
 mysql-connector-python-test:
-	make recreate-table
 	python3 mysql_connector_python_example.py
 
diff --git a/README-zh.md b/README-zh.md
@@ -4,36 +4,63 @@
 
 [English](/README.md) | 中文
 
-**tidb-example-python** 是 PingCAP 为 Python 连接 [TiDB](https://docs.pingcap.com/tidb/stable) 而编写的示例项目。你可以在这里找到以下示例：
+**tidb-example-python** 是 PingCAP 为 Python 连接 [TiDB](https://docs.pingcap.com/tidb/stable) 而编写的示例项目。其所属文档为 [TiDB 开发者文档](https://docs.pingcap.com/zh/tidb/stable/dev-guide-overview)。你可以在这里找到以下示例：
 
-**Driver**
+## Driver
 
 - [PyMySQL](/pymysql_example.py) 示例
 - [mysqlclient](/mysqlclient_example.py) 示例
 - [mysql-connector-python](/mysql_connector_python_example.py) 示例
 
-**ORM**
+## ORM
 
 - [SQLAlchemy](/sqlalchemy_example.py) 示例
 - [peewee](/peewee_example.py) 示例
 
-**Framework**
+## Framework
 
 - [Django](/django_example) 示例
 
-**Scenario**
+## Scenario
 
 - [Serverless Tier 连接](/serverless_tier_example.py)示例
 - [批量删除场景](/batch_delete.py)示例
 - [批量更新场景](/batch_update.py)示例
 - [避免写偏斜](/write_skew_example.py)示例
 - [乐观/悲观事务](/txn_example.py)示例
 
-## 依赖
+## 前提要求
 
-- [TiDB](https://docs.pingcap.com/tidb/stable)
-- [mycli](https://www.mycli.net/)
-- [Python 3.6+](https://www.python.org/)
+- 已安装 [Python](https://www.python.org/)，推荐版本 3.10 及以上。
+- 启动你的 TiDB 集群，如果你还没有 TiDB 集群：
+
+  - 推荐参考[创建 TiDB Serverless 集群](https://docs.pingcap.com/zh/tidb/stable/dev-guide-build-cluster-in-cloud)文档创建你自己的 TiDB Cloud 集群。
+  - 备选参考[部署本地测试 TiDB 集群](https://docs.pingcap.com/zh/tidb/stable/quick-start-with-tidb)或[部署正式 TiDB 集群](https://docs.pingcap.com/zh/tidb/stable/production-deployment-using-tiup)文档创建本地集群。
+
+- 已获取代码并安装依赖
+
+    ```bash
+    git clone https://github.com/pingcap-inc/tidb-example-python.git
+    cd tidb-example-python
+    pip install requirement.txt
+    ```
+
+- 已正确配置代码目录下的 `.env` 配置文件，你可以用 `cp .env.example .env` 复制初始配置文件后进行更改。如果你不知道这些信息如何获取，请参考 [Obtain the connection parameters](https://docs.pingcap.com/tidbcloud/connect-via-standard-connection-serverless#obtain-the-connection-parameters) 及 [Where is the CA root path on my system?](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-tier-clusters#where-is-the-ca-root-path-on-my-system) 文档：
+
+    ```properties
+    # TiDB 集群地址
+    TIDB_HOST='xxxxxxxx.aws.tidbcloud.com'
+    # TiDB 集群端口
+    TIDB_PORT='4000'
+    # TiDB 集群用户名
+    TIDB_USER='xxxxxxxxxxx.root'
+    # TiDB 集群密码
+    TIDB_PASSWORD='xxxxxxx'
+    # 希望本示例使用的数据库名称
+    TIDB_DB_NAME='test'
+    # 使用的 TiDB 集群如果要求使用安全连接，并使用自定义的 CA 证书时
+    CA_PATH='/etc/ssl/cert.pem'
+    ```
 
 ## 运行
 
@@ -45,22 +72,8 @@ make test
 
 ### 单独运行某项测试
 
-以 `peewee_example.py` 为例：
-
-1. 安装依赖：
+以 **peewee_example.py** 为例：`python3 peewee_example.py`。
 
-    ```bash
-    pip install -r requirement.txt
-    ```
-
-2. 初始化表
-
-    ```bash
-    mycli --host 127.0.0.1 --port 4000 -u root --no-warn < player_init.sql
-    ```
+### 预期输出
 
-3. 运行脚本
-
-    ```bash
-    python3 peewee_example.py
-    ```
+[预期输出](/Expected-Output.md)
diff --git a/README.md b/README.md
@@ -4,63 +4,76 @@
 
 English | [中文](/README-zh.md)
 
-**tidb-example-python** is a sample project written by PingCAP for Python to connect to [TiDB](https://docs.pingcap.com/tidb/stable). You can find the following examples here.
+**tidb-example-python** is a sample project written by PingCAP for Python to connect to [TiDB](https://docs.pingcap.com/tidb/stable). This document belongs to the [TiDB developer documentation](https://docs.pingcap.com/tidb/stable/dev-guide-overview). You can find the following examples here.
 
-**Driver**
+## Driver
 
 - [PyMySQL](/pymysql_example.py) example
 - [mysqlclient](/mysqlclient_example.py) example
 - [mysql-connector-python](/mysql_connector_python_example.py) example
 
-**ORM**
+## ORM
 
 - [SQLAlchemy](/sqlalchemy_example.py) example
 - [peewee](/peewee_example.py) example
 
-**Framework**
+## Framework
 
 - [Django](/django_example) example
 
-**Scenario**
+## Scenario
 
 - [Serverless Tier connection](/serverless_tier_example.py) example
 - [Butch delete](/batch_delete.py) example
 - [Butch update](/batch_update.py) example
 - [Avoid write skew](/write_skew_example.py) example
 - [Optimistic and pessimistic transaction](/txn_example.py) example
 
-## Dependcies
+## Prerequisites
 
-- [TiDB](https://docs.pingcap.com/tidb/stable)
-- [mycli](https://www.mycli.net/)
-- [Python 3.6+](https://www.python.org/)
+- Python installed (recommended version 3.10 and above).
+- Start your TiDB cluster. If you don't have a TiDB cluster yet:
 
-## Run
+  - We recommend referring to the document [Create a TiDB Serverless Cluster](https://docs.pingcap.com/tidb/stable/dev-guide-build-cluster-in-cloud) to create your own TiDB Cloud cluster.
+  - Alternatively, you can refer to the documents [Deploy a Local Testing TiDB Cluster](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb) or [Deploy a Formal TiDB Cluster](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) to create a local cluster.
 
-### Run the Whole ORM and Driver Test
+- Get the code and install the dependencies
 
-```bash
-make test
-```
+  ```bash
+  git clone https://github.com/pingcap-inc/tidb-example-python.git
+  cd tidb-example-python
+  pip install -r requirement.txt
+  ```
 
-### Run the particular test
+- Configure the `.env` file in the code directory correctly. You can use `cp .env.example .env` to copy the initial configuration file and make changes accordingly. If you are unsure how to obtain this information, please refer to the documents [Obtain the connection parameters](https://docs.pingcap.com/tidbcloud/connect-via-standard-connection-serverless#obtain-the-connection-parameters) and [Where is the CA root path on my system?](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-tier-clusters#where-is-the-ca-root-path-on-my-system):
 
-Using run the `peewee_example.py` script as an example:
+  ```properties
+  # TiDB cluster address
+  TIDB_HOST='xxxxxxxx.aws.tidbcloud.com'
+  # TiDB cluster port
+  TIDB_PORT='4000'
+  # TiDB cluster username
+  TIDB_USER='xxxxxxxxxxx.root'
+  # TiDB cluster password
+  TIDB_PASSWORD='xxxxxxx'
+  # The database name to be used for this example
+  TIDB_DB_NAME='test'
+  # The location of the CA certificate on the instance where the example is run. Required when the used cluster require secure connection
+  CA_PATH='/etc/ssl/cert.pem'
+  ```
 
-1. Install dependcy.
+## Run
 
-    ```bash
-    pip install -r requirement.txt
-    ```
+### Run the Entire ORM / Driver Test
+
+```bash
+make test
+```
 
-2. Initial the table.
+### Run a specific test individually
 
-    ```bash
-    mycli --host 127.0.0.1 --port 4000 -u root --no-warn < player_init.sql
-    ```
+Taking **peewee_example.py** as an example: `python3 peewee_example.py`.
 
-3. Run the script.
+### Expected output
 
-    ```bash
-    python3 peewee_example.py
-    ```
+[Expected output](/Expected-Output.md)
diff --git a/batch_delete.py b/batch_delete.py
@@ -12,20 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import MySQLdb
 import datetime
 import time
+from connect_tidb import get_mysqlclient_connection
 
-connection = MySQLdb.connect(
-    host="127.0.0.1",
-    port=4000,
-    user="root",
-    password="",
-    database="bookshop",
-    autocommit=True
-)
-
-with connection:
+with get_mysqlclient_connection() as connection:
     with connection.cursor() as cursor:
         start_time = datetime.datetime(2022, 4, 15)
         end_time = datetime.datetime(2022, 4, 15, 0, 15)

diff --git a/batch_update.py b/batch_update.py
@@ -11,18 +11,8 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-import MySQLdb
 import time
-
-connection = MySQLdb.connect(
-    host="127.0.0.1",
-    port=4000,
-    user="root",
-    password="",
-    database="bookshop",
-    autocommit=True
-)
-
+from connect_tidb import get_mysqlclient_connection
 
 def update_batch(cur, last_book_id: int = None, last_user_id: int = None) -> (int, int):
     if last_book_id is None or last_user_id is None:
@@ -49,7 +39,7 @@ def update_batch(cur, last_book_id: int = None, last_user_id: int = None) -> (in
     return latest_book_id, latest_user_id
 
 
-with connection:
+with get_mysqlclient_connection() as connection:
     with connection.cursor() as cursor:
         # add a column `ten_point`
         # cursor.execute("ALTER TABLE `bookshop`.`ratings` ADD COLUMN `ten_point` BOOL NOT NULL DEFAULT FALSE")