add README

README-zh.md

@@ -0,0 +1,141 @@
+# 使用 peewee 连接 TiDB
+
+[English](/README.md) | 中文
+
+这是 PingCAP 为 peewee 编写的用于连接 TIDB 的示例项目
+> TiDB 是一个兼容 MySQL 的数据库。[peewee](https://docs.peewee-orm.com/) 为当前流行的开源 Python ORM (Object Relational Mapper) 之一。
+
+## 前置要求
+
+- 推荐 [Python 3.8 及以上版本](https://www.python.org/downloads/)
+- [Git](https://git-scm.com/downloads)
+- TiDB 集群。如果你还没有 TiDB 集群，可以按照以下方式创建：
+  - （推荐方式）参考[创建 TiDB Serverless 集群](https://docs.pingcap.com/tidbcloud/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)，创建本地集群。
+
+## 开始实践
+
+### 1. 克隆示例代码仓库到本地
+
+```shell
+git clone https://github.com/tidb-samples/tidb-python-peewee-quickstart.git
+cd tidb-python-peewee-quickstart
+```
+
+### 2. 安装依赖 (包括 peewee 和 PyMySQL)
+
+```shell
+pip install -r requirements.txt
+```
+
+#### 为什么安装 PyMySQL？
+
+Peewee 是一个支持多种数据库的 ORM 库。它是对数据库的高层抽象，可以帮助开发者以更面向对象的方式编写 SQL 语句。但 peewee 并不提供数据库驱动，因此需要单独安装用于连接 TiDB 的驱动。本示例项目使用 PyMySQL 作为数据库驱动。PyMySQL 是一个与 TiDB 兼容的纯 Python 实现的 MySQL 客户端库，并可以在所有平台上安装。更多信息，参考 [peewee 官方文档](https://docs.peewee-orm.com/en/latest/peewee/database.html?highlight=mysql#using-mysql)。
+
+### 3. 配置连接信息
+
+<details open>
+<summary><b>(选项 1) TiDB Serverless</b></summary>
+
+1. 在 TiDB Cloud 控制台中，打开 [Clusters](https://tidbcloud.com/console/clusters) 页面，选择你的 TiDB Serverless 集群，进入 **Overview** 页面，点击右上角的 **Connect** 按钮。
+2. 确认窗口中的配置和你的运行环境一致。
+    - **Endpoint Type** 为 **Public**
+    - **Connect With** 为 **General**
+    - Operating System 为你的运行环境
+    > 如果你在 Windows Subsystem for Linux (WSL) 中运行，请切换为对应的 Linux 发行版。
+3. 点击 **Generate password** 生成密码。
+    > 如果你之前已经生成过密码，可以直接使用原密码，或点击 **Reset Password** 重新生成密码。
+4. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`：
+
+    ```shell
+    cp .env.example .env
+    ```
+
+5. 复制并粘贴对应连接字符串至 `.env` 中。示例结果如下：
+
+   ```python
+    TIDB_HOST='{gateway-region}.aws.tidbcloud.com'
+    TIDB_PORT='4000'
+    TIDB_USER='{prefix}.root'
+    TIDB_PASSWORD='{password}'
+    TIDB_DB_NAME='test'
+    CA_PATH='{ca_path}'
+    ```
+
+    注意替换 `{}` 中的占位符为 **Connect** 窗口中获得的值。
+
+    TiDB Serverless 要求使用安全连接，你可以参考 [TiDB Cloud 文档](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters#root-certificate-default-path)获取不同操作系统下证书的路径。
+
+6. 保存文件。
+
+</details>
+
+<details>
+
+<summary><b>(选项 2) TiDB Dedicated</b></summary>
+
+1. 在 TiDB Cloud Web Console 中，选择你的 TiDB Dedicated 集群，进入 **Overview** 页面，点击右上角的 **Connect** 按钮。点击 **Allow Access from Anywhere** 并点击 **Download TiDB cluster CA** 下载证书。
+    > 更多配置细节，可参考 [TiDB Dedicated 标准连接教程](https://docs.pingcap.com/tidbcloud/connect-via-standard-connection).
+
+2. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`：
+
+    ```shell
+    cp .env.example .env
+    ```
+
+3. 复制并粘贴对应的连接字符串至 `.env` 中。示例结果如下：
+
+   ```python
+    TIDB_HOST='{host}.clusters.tidb-cloud.com'
+    TIDB_PORT='4000'
+    TIDB_USER='{username}'
+    TIDB_PASSWORD='{password}'
+    TIDB_DB_NAME='test'
+    CA_PATH='{your-downloaded-ca-path}'
+    ```
+
+    注意替换 `{}` 中的占位符为 **Connect** 窗口中获得的值，并配置前面步骤中下载好的证书路径。
+
+4. 保存文件。
+
+</details>
+
+<details>
+<summary><b>(选项 3) 自建 TiDB</b></summary>
+
+1. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`：
+
+    ```shell
+    cp .env.example .env
+    ```
+
+2. 复制并粘贴对应 TiDB 的连接字符串至 `.env` 中。示例结果如下：
+
+    ```python
+    TIDB_HOST='{tidb_server_host}'
+    TIDB_PORT='4000'
+    TIDB_USER='root'
+    TIDB_PASSWORD='{password}'
+    TIDB_DB_NAME='test'
+    ```
+
+    注意替换 `{}` 中的占位符为你的 TiDB 对应的值，并删除 `CA_PATH` 这行。如果你在本机运行 TiDB，默认 Host 地址为 `127.0.0.1`，密码为空。
+
+3. 保存文件。
+
+</details>
+
+### 4. 运行示例代码
+
+```shell
+python peewee_example.py
+```
+
+### 5. 期望输出
+
+[期望的输出](/Expected-Output.txt)
+
+## 下一步
+
+- 你可以继续阅读开发者文档，以获取更多关于 TiDB 的开发者知识。例如：[插入数据](https://docs.pingcap.com/zh/tidb/stable/dev-guide-insert-data)，[更新数据](https://docs.pingcap.com/zh/tidb/stable/dev-guide-update-data)，[删除数据](https://docs.pingcap.com/zh/tidb/stable/dev-guide-delete-data)，[单表读取](https://docs.pingcap.com/zh/tidb/stable/dev-guide-get-data-from-single-table)，[事务](https://docs.pingcap.com/zh/tidb/stable/dev-guide-transaction-overview)，[SQL 性能优化](https://docs.pingcap.com/zh/tidb/stable/dev-guide-optimize-sql-overview)等。
+- 如果你更倾向于参与课程进行学习，我们也提供专业的 [TiDB 开发者课程](https://cn.pingcap.com/courses-catalog/back-end-developer/)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。

README.md

@@ -0,0 +1,140 @@
+# Connecting to TiDB cluster with peewee
+
+English | [中文](/README-zh.md)
+
+This a sample project written by PingCAP for peewee to connect to TiDB.
+> TiDB is a MySQL-compatible database, and [peewee](https://docs.peewee-orm.com/) is a popular Object Relational Mapper (ORM) for Python.
+
+## Prerequisites
+
+- [Python 3.8 or higher](https://www.python.org/downloads/)
+- [Git](https://git-scm.com/downloads)
+- A TiDB cluster. If you don't have a TiDB cluster, you can create one as follows:
+  - (Recommended) Follow [Creating a TiDB Serverless Cluster](https://docs.pingcap.com/tidbcloud/dev-guide-build-cluster-in-cloud) to create your own TiDB Cloud cluster.
+  - Follow [Deploy a Local Test TiDB Cluster](https://docs.pingcap.com/tidb/stable/quick-start-with-tidb#deploy-a-local-test-cluster) or [Deploy a Production TiDB Cluster](https://docs.pingcap.com/tidb/stable/production-deployment-using-tiup) to create a local cluster
+
+## Getting started
+
+### 1. Clone the repository
+
+```shell
+git clone https://github.com/tidb-samples/tidb-python-peewee-quickstart.git
+cd tidb-python-peewee-quickstart
+```
+
+### 2. Install dependencies (including peewee and PyMySQL)
+
+```shell
+pip install -r requirements.txt
+```
+
+#### Why use PyMySQL?
+
+Peewee is an ORM library that works with multiple databases. It provides a high-level abstraction of the database, which helps developers write SQL statements in a more object-oriented way. However, peewee does not include a database driver. To connect to a database, you need to install a database driver. This sample application uses PyMySQL as the database driver, which is a pure Python MySQL client library that is compatible with TiDB and can be installed on all platforms. For more information, refer to [peewee official documentation](https://docs.peewee-orm.com/en/latest/peewee/database.html?highlight=mysql#using-mysql).
+
+### 3. Configure connection information
+
+<details open>
+<summary><b>(Option 1) TiDB Serverless</b></summary>
+
+1. In the TiDB Cloud, navigate to the [Clusters](https://tidbcloud.com/console/clusters) page, select your TiDB Serverless cluster. Go to the **Overview** page, and click the **Connect** button in the upper right corner.
+2. Ensure the configurations in the confirmation window match your operating environment.
+    - **Endpoint Type** is set to **Public**
+    - **Connect With** is set to **General**
+    - Operating System matches your environment
+    > If you are running in Windows Subsystem for Linux (WSL), switch to the corresponding Linux distribution.
+3. Click **Create password** to create a password.
+    > If you have created a password before, you can either use the original password or click **Reset Password** to generate a new one.
+4. Run the following command to copy `.env.example` and rename it to `.env`:
+
+    ```shell
+    cp .env.example .env
+    ```
+
+5. Copy and paste the corresponding connection string into the `.env` file. Example result is as follows:
+
+   ```python
+    TIDB_HOST='{gateway-region}.aws.tidbcloud.com'
+    TIDB_PORT='4000'
+    TIDB_USER='{prefix}.root'
+    TIDB_PASSWORD='{password}'
+    TIDB_DB_NAME='test'
+    CA_PATH='{ca_path}'
+    ```
+
+    Be sure to replace the placeholders `{}` with the values obtained from the connection dialog.
+
+    TiDB Serverless requires a secure connection, you can refer to the [TLS Connections to TiDB Serverless](https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-clusters) to get the certificate paths for different operating systems.
+
+6. Save the `.env` file.
+
+</details>
+
+<details>
+
+<summary><b>(Option 2) TiDB Dedicated</b></summary>
+
+1. In the TiDB Cloud, select your TiDB Dedicated cluster. Go to the **Overview** page, and click the **Connect** button in the upper right corner. Click **Allow Access from Anywhere** and then click **Download TiDB cluster CA** to download the certificate.
+    > For more configuration details, refer to [TiDB Dedicated Standard Connection](https://docs.pingcap.com/tidbcloud/connect-via-standard-connection).
+2. Run the following command to copy `.env.example` and rename it to `.env`:
+
+    ```shell
+    cp .env.example .env
+    ```
+
+3. Copy and paste the corresponding connection string into the `.env` file. Example result is as follows:
+
+   ```python
+    TIDB_HOST='{host}.clusters.tidb-cloud.com'
+    TIDB_PORT='4000'
+    TIDB_USER='{username}'
+    TIDB_PASSWORD='{password}'
+    TIDB_DB_NAME='test'
+    CA_PATH='{your-downloaded-ca-path}'
+    ```
+
+    Be sure to replace the placeholders `{}` with the values obtained from the **Connect** window, and configure `CA_PATH` with the certificate path downloaded in the previous step.
+
+4. Save the `.env` file.
+
+</details>
+
+<details>
+<summary><b>(Option 3) Self-Hosted TiDB</b></summary>
+
+1. Run the following command to copy `.env.example` and rename it to `.env`:
+
+    ```shell
+    cp .env.example .env
+    ```
+
+2. Copy and paste the corresponding connection string into the `.env` file. Example result is as follows:
+
+    ```python
+    TIDB_HOST='{tidb_server_host}'
+    TIDB_PORT='4000'
+    TIDB_USER='root'
+    TIDB_PASSWORD='{password}'
+    TIDB_DB_NAME='test'
+    ```
+
+    Be sure to replace the placeholders `{}` with the values, and remove the `CA_PATH` line. If you are running TiDB locally, the default host address is `127.0.0.1`, and the password is empty.
+
+3. Save the `.env` file.
+
+</details>
+
+### 4. Run
+
+```shell
+python peewee_example.py
+```
+
+### 5. Expected output
+
+[Expected output](/Expected-Output.txt)
+
+## Next Steps
+
+- You can continue reading the developer documentation to get more knowledge about TiDB development, such as: [Insert Data](https://docs.pingcap.com/tidb/stable/dev-guide-insert-data), [Update Data](https://docs.pingcap.com/tidb/stable/dev-guide-update-data), [Delete Data](https://docs.pingcap.com/tidb/stable/dev-guide-delete-data), [Single Table Reading](https://docs.pingcap.com/tidb/stable/dev-guide-get-data-from-single-table), [Transactions](https://docs.pingcap.com/tidb/stable/dev-guide-transaction-overview), [SQL Performance Optimization](https://docs.pingcap.com/tidb/stable/dev-guide-optimize-sql-overview), etc.
+- If you prefer to learn through courses, we also offer professional [TiDB Developer Courses](https://www.pingcap.com/education/), and provide [TiDB certifications](https://www.pingcap.com/education/certification/) after the exam.