add README

README-zh.md

@@ -0,0 +1,166 @@
+# 使用 Django 和 TiDB 构建应用程序
+
+English | [中文](/README-zh.md)
+
+这是 PingCAP 为 Django 编写的使用 TIDB 构建应用程序的示例项目。
+
+这是一个关于游戏的例子，每个玩家有三个属性：姓名 `name`, 金币数 `coins` 和货物数 `goods`。且每个玩家都拥有一个字段 `id`，作为玩家的唯一标识。玩家在金币数和货物数充足的情况下，可以自由地交易。
+
+## 前置要求
+
+- 推荐 [Python 3.10 及以上版本](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-django-quickstart.git
+cd tidb-python-django-quickstart
+```
+
+### 2. 安装依赖 (包括 Django, django-tidb 和 mysqlclient)
+
+```shell
+pip install -r requirements.txt
+```
+
+#### 为什么我们还需要安装 django-tidb 和 mysqlclient？
+
+- django-tidb 是由 PingCAP 开发的用于解决 Django 和 TiDB 之间的兼容性问题。更多信息请参考 [django-tidb 仓库](https://github.com/pingcap/django-tidb)
+- mysqlclient 是 Django 和 django-tidb 官方支持的 Python MySQL 驱动，它帮助 Django 和 TiDB 实现具体通信，并且提供了较高的性能。更多信息请参考 [mysqlclient 仓库](https://github.com/PyMySQL/mysqlclient)
+
+#### 如何选择正确的 django-tidb 版本
+
+- django-tidb 的版本应该和 django 的版本匹配，例如，如果你使用的是 `django 4.2.x`，你应该安装 `django-tidb 4.2.x`（最小版本号不需要完全一致，推荐使用各自的最新小版本）。你可以在 [django-tidb 官方文档](https://github.com/pingcap/django-tidb#installing-django-tidb)
+
+#### 安装 mysqlclient 时遇到问题
+
+- 如果这是你第一次安装 mysqlclient，你可能会遇到一些问题，因为它不仅仅是一个纯 Python 包，还需要一些 C 扩展。为了解决这些问题，请参考 [mysqlclient 官方文档](https://github.com/PyMySQL/mysqlclient#install)
+
+### 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=''
+    ```
+
+    注意替换 `{}` 中的占位符为 **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)获取不同操作系统下证书的路径。
+
+6. 保存文件。
+
+<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 manage.py migrate
+```
+
+### 5. 运行服务器
+
+```shell
+python manage.py runserver
+```
+
+> 默认端口为 8000。如果你想修改端口，可以在命令后添加端口号，例如：`python manage.py runserver 8080`
+
+### 6. 探索示例应用
+
+在浏览器中访问 <http://127.0.0.1:8000>。如果你修改了端口号，将 8000 替换为你的端口号。
+
+在应用中，你可以：
+
+- 创建新玩家
+- 批量创建玩家
+- 查看所有玩家
+- 查看玩家详情
+- 删除玩家
+- 与玩家交易
+
+## 下一步
+
+- 你可以继续阅读开发者文档，以获取更多关于 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,165 @@
+# Build a Django App with TiDB
+
+English | [中文](/README-zh.md)
+
+This a sample project written by PingCAP for Django to connect to TiDB.
+
+This is an example of a game where each player has three attributes: `name`, `coins` and `goods`, and each player has a field `id` that uniquely identifies the player. Players can trade freely if they have enough coins and goods.
+
+## Prerequisites
+
+- [Python **3.10** 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-django-quickstart.git
+cd tidb-python-django-quickstart
+```
+
+### 2. Install dependencies (including Django, django-tidb and mysqlclient)
+
+```shell
+pip install -r requirements.txt
+```
+
+#### Why do we need to install django-tidb and mysqlclient?
+
+- `django-tidb` is a TiDB dialect for Django that addresses compatibility issues between them. For more information, please refer to the [django-tidb repository](https://github.com/pingcap/django-tidb).
+- `mysqlclient` is a MySQL driver for Python that is officially supported by Django and django-tidb. It enables communication between Django and the TiDB server. For more information, please refer to the [mysqlclient repository](https://github.com/PyMySQL/mysqlclient).
+
+#### How to choose the right version of django-tidb
+
+The version of `django-tidb` should match the version of `django`, for example, if you are using `django 4.2.x`, you should install `django-tidb 4.2.x` (the minor release number do not need to be the same, use the latest minor release of each). You can find the detailed version mapping in the [django-tidb official documentation](https://github.com/pingcap/django-tidb#installing-django-tidb)
+
+#### Encountering problems when installing mysqlclient
+
+If this is your first time installing mysqlclient, you may encounter some problems as it is not only a pure Python package, but also requires some C extensions. To resolve them, please refer to the [mysqlclient official documentation](https://github.com/PyMySQL/mysqlclient#install)
+
+### 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=''
+    ```
+
+    Be sure to replace the placeholders `{}` with the values obtained from the connection dialog.
+
+    TiDB Serverless requires a secure connection. Since the `ssl_mode` of mysqlclient defaults to `PREFERRED`, you don't need to manually specify `CA_PATH`. Just leave it empty. But if you have a special reason to specify `CA_PATH` manually, 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>
+
+<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. Migrate the database
+
+```shell
+python manage.py migrate
+```
+
+### 5. Run server
+
+```shell
+python manage.py runserver
+```
+
+> The default port is 8000. If you want to change the port, you can add the port number after the command, for example: `python manage.py runserver 8080`
+
+### 6. Explore the sample app
+
+Access the application in your browser via <http://127.0.0.1:8000>. If you've modified the port, replace 8000 with your specified port number.
+
+Within the application, you can:
+
+- Create a new player
+- Bulk create players
+- View all players at
+- View a player's details
+- Delete a player
+- Trade with a player
+
+## 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.