From d7393a4eec5a7c9779bedf519784f594c3cf0690 Mon Sep 17 00:00:00 2001 From: wd0517 Date: Tue, 22 Aug 2023 19:14:48 +0800 Subject: [PATCH] add README --- README-zh.md | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 331 insertions(+) create mode 100644 README-zh.md create mode 100644 README.md diff --git a/README-zh.md b/README-zh.md new file mode 100644 index 0000000..c0d3406 --- /dev/null +++ b/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. 配置连接信息 + +
+(选项 1) TiDB Serverless + +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. 保存文件。 + +
+ +(选项 2) TiDB Dedicated + +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. 保存文件。 + +
+ +
+(选项 3) 自建 TiDB + +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. 保存文件。 + +
+ +### 4. 迁移数据库 + +```shell +python manage.py migrate +``` + +### 5. 运行服务器 + +```shell +python manage.py runserver +``` + +> 默认端口为 8000。如果你想修改端口，可以在命令后添加端口号，例如：`python manage.py runserver 8080` + +### 6. 探索示例应用 + +在浏览器中访问 。如果你修改了端口号，将 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)。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..3d8ba85 --- /dev/null +++ b/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 + +
+(Option 1) TiDB Serverless + +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. + +
+ +(Option 2) TiDB Dedicated + +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. + +
+ +
+(Option 3) Self-Hosted TiDB + +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. + +
+ +### 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 . 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.