diff --git a/markdown-pages/zh/tidb/release-7.5/TOC.md b/markdown-pages/zh/tidb/release-7.5/TOC.md index 73428aba..e8c64c82 100644 --- a/markdown-pages/zh/tidb/release-7.5/TOC.md +++ b/markdown-pages/zh/tidb/release-7.5/TOC.md @@ -40,14 +40,14 @@ - [node-mysql2](/develop/dev-guide-sample-application-nodejs-mysql2.md) - [mysql.js](/develop/dev-guide-sample-application-nodejs-mysqljs.md) - [Prisma](/develop/dev-guide-sample-application-nodejs-prisma.md) + - [Sequelize](/develop/dev-guide-sample-application-nodejs-sequelize.md) - [TypeORM](/develop/dev-guide-sample-application-nodejs-typeorm.md) + - [Next.js](/develop/dev-guide-sample-application-nextjs.md) + - [AWS Lambda](/develop/dev-guide-sample-application-aws-lambda.md) - Ruby - [mysql2](/develop/dev-guide-sample-application-ruby-mysql2.md) - [Rails](/develop/dev-guide-sample-application-ruby-rails.md) - 连接到 TiDB - - GUI 数据库工具 - - [MySQL Workbench](/develop/dev-guide-gui-mysql-workbench.md) - - [Navicat](/develop/dev-guide-gui-navicat.md) - [选择驱动或 ORM 框架](/develop/dev-guide-choose-driver-or-orm.md) - [连接到 TiDB](/develop/dev-guide-connect-to-tidb.md) - [连接池与连接参数](/develop/dev-guide-connection-parameters.md) @@ -131,7 +131,6 @@ - [从大数据量 MySQL 迁移数据到 TiDB](/migrate-large-mysql-to-tidb.md) - [从小数据量分库分表 MySQL 合并迁移数据到 TiDB](/migrate-small-mysql-shards-to-tidb.md) - [从大数据量分库分表 MySQL 合并迁移数据到 TiDB](/migrate-large-mysql-shards-to-tidb.md) - - [从 MariaDB 迁移数据到 TiDB](/migrate-from-mariadb.md) - [从 CSV 文件迁移数据到 TiDB](/migrate-from-csv-files-to-tidb.md) - [从 SQL 文件迁移数据到 TiDB](/migrate-from-sql-files-to-tidb.md) - [从 Parquet 文件迁移数据到 TiDB](/migrate-from-parquet-files-to-tidb.md) @@ -820,7 +819,9 @@ - [`SHOW FIELDS FROM`](/sql-statements/sql-statement-show-fields-from.md) - [`SHOW GRANTS`](/sql-statements/sql-statement-show-grants.md) - [`SHOW IMPORT JOB`](/sql-statements/sql-statement-show-import-job.md) + - [`SHOW INDEX`](/sql-statements/sql-statement-show-index.md) - [`SHOW INDEXES`](/sql-statements/sql-statement-show-indexes.md) + - [`SHOW KEYS`](/sql-statements/sql-statement-show-keys.md) - [`SHOW MASTER STATUS`](/sql-statements/sql-statement-show-master-status.md) - [`SHOW PLACEMENT`](/sql-statements/sql-statement-show-placement.md) - [`SHOW PLACEMENT FOR`](/sql-statements/sql-statement-show-placement-for.md) diff --git a/markdown-pages/zh/tidb/release-7.5/develop/dev-guide-sample-application-aws-lambda.md b/markdown-pages/zh/tidb/release-7.5/develop/dev-guide-sample-application-aws-lambda.md new file mode 100644 index 00000000..23444640 --- /dev/null +++ b/markdown-pages/zh/tidb/release-7.5/develop/dev-guide-sample-application-aws-lambda.md @@ -0,0 +1,357 @@ +--- +title: 在 AWS Lambda 函数中使用 mysql2 连接 TiDB +summary: 本文介绍如何在 AWS Lambda 函数中使用 TiDB 和 mysql2 构建 CRUD 应用程序，并提供了一个简单的示例代码片段。 +--- + +# 在 AWS Lambda 函数中使用 mysql2 连接 TiDB + +TiDB 是一个兼容 MySQL 的数据库，[AWS Lambda 函数](https://aws.amazon.com/lambda/) 是一个计算服务，[node-mysql2](https://github.com/sidorares/node-mysql2) 是一个与 [mysqljs/mysql](https://github.com/mysqljs/mysql) 兼容的面向 Node.js 的 MySQL 驱动 + +在本教程中，您可以学习如何在AWS Lambda函数中使用TiDB和mysql2来完成以下任务： + +- 配置你的环境。 +- 使用 node-mysql2 驱动连接到 TiDB 集群。 +- 构建并运行你的应用程序。你也可以参考[示例代码片段](#示例代码片段)，完成基本的 CRUD 操作。 +- 部署您的AWS Lambda函数。 + +> **注意** +> +> 本文档适用于 TiDB Serverless 和本地部署的 TiDB。 + +## 前置需求 + +为了能够顺利完成本教程，你需要提前： + +- 在你的机器上安装 [Node.js](https://nodejs.org/en) 18.x 或以上版本。 +- 在你的机器上安装 [Git](https://git-scm.com/downloads)。 +- 准备一个 TiDB 集群。 +- 一个具有管理员权限的 [AWS 用户](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)。 +- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) +- [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html) + +**如果你还没有 TiDB 集群，可以按照以下方式创建：** + +- （推荐方式）参考[创建 TiDB Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-serverless-集群)，创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + +如果您还没有AWS账户或用户，您可以按照 [Lambda 入门](https://docs.aws.amazon.com/zh_cn/lambda/latest/dg/getting-started.html) 指南中的步骤来创建它们。 + +## 运行代码并连接到 TiDB + +本小节演示如何运行示例应用程序的代码，并连接到 TiDB。 + +> **注意** +> +>要获取完整的代码片段和运行说明，请参考 [tidb-samples/tidb-aws-lambda-quickstart](https://github.com/tidb-samples/tidb-aws-lambda-quickstart) GitHub存储库。 + +### 步骤 1：克隆示例应用程序仓库 + +在终端窗口中运行以下命令来克隆示例代码仓库： + +```bash +git clone git@github.com:tidb-samples/tidb-aws-lambda-quickstart.git +cd tidb-aws-lambda-quickstart +``` + +### 步骤 2：安装依赖 + +运行以下命令来安装示例应用程序所需的包（包括 mysql2）： + +```bash +npm install +``` + +### 步骤 3：配置连接信息 + +根据您选择的 TiDB 部署选项，连接到您的 TiDB 集群。 + + + +
+ +1. 导航到 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，然后点击目标集群的名称，进入其概览页面。 + +2. 在右上角点击 **Connect**。将显示一个连接对话框。 + +3. 确认对话框中的选项配置和你的运行环境一致。 + + - **Endpoint Type** 为 `Public`。 + - **Branch** 选择 `main`。 + - **Connect With** 选择 `General`。 + - **Operating System** 为运行示例代码所在的操作系统。 + + > **Note** + > + > 在 Node.js 应用程序中，您无需提供 SSL CA 证书，因为在建立 TLS（SSL）连接时，默认情况下 Node.js 使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)。 + +4. 如果你还没有设置密码，点击 **Generate Password** 按钮生成一个随机的密码。 + + > **Tip** + > + > 如果您之前生成过密码，您可以使用原始密码，或者点击 **Reset Password** 来生成一个新密码。 + +5. 将相应的连接字符串复制并粘贴到 `env.json` 文件中。以下是一个示例： + + ```json + { + "Parameters": { + "TIDB_HOST": "{gateway-region}.aws.tidbcloud.com", + "TIDB_PORT": "4000", + "TIDB_USER": "{prefix}.root", + "TIDB_PASSWORD": "{password}" + } + } + ``` + + 请将连接对话框中获取的值替换{}中的占位符。 + +
+ +
+ +将相应的连接字符串复制并粘贴到 `env.json` 文件中。以下是一个示例： + +```json +{ + "Parameters": { + "TIDB_HOST": "{tidb_server_host}", + "TIDB_PORT": "4000", + "TIDB_USER": "root", + "TIDB_PASSWORD": "{password}" + } +} +``` + +
+ + + +### 步骤 4：运行示例应用程序 + +1. （先决条件）安装[AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)。 + +2. 构建捆绑包： + + ```bash + npm run build + ``` + +3. 调用示例Lambda函数： + + ```bash + sam local invoke --env-vars env.json -e events/event.json "tidbHelloWorldFunction" + ``` + +4. 在终端中检查输出。如果输出类似于以下内容，则连接成功： + + ```bash + {"statusCode":200,"body":"{\"results\":[{\"Hello World\":\"Hello World\"}]}"} + ``` + +确认连接成功后，您可以按照 [下一节](#部署-aws-lambda-函数) 中的步骤来部署AWS Lambda函数。 + +## 部署 AWS Lambda 函数 + +您可以使用 [SAM CLI](#sam-cli-部署推荐) 或 [AWS Lambda 控制台](#web控制台部署) 来部署 AWS Lambda 函数。 + +### SAM CLI 部署（推荐） + +1. ([前置需求](#前置需求)) 安装 [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html). + +2. 构建应用程序包： + + ```bash + npm run build + ``` + +3. 更新 [`template.yml`](https://github.com/tidb-samples/tidb-aws-lambda-quickstart/blob/main/template.yml) 文件中的环境变量： + + ```yaml + Environment: + Variables: + TIDB_HOST: {tidb_server_host} + TIDB_PORT: 4000 + TIDB_USER: {prefix}.root + TIDB_PASSWORD: {password} + ``` + +4. 设置环境变量 (参考 [使用短期凭证进行身份验证](https://docs.aws.amazon.com/zh_cn/cli/latest/userguide/cli-authentication-short-term.html)): + + ```bash + export AWS_ACCESS_KEY_ID={your_access_key_id} + export AWS_SECRET_ACCESS_KEY={your_secret_access_key} + export AWS_SESSION_TOKEN={your_session_token} + ``` + +5. 部署 AWS Lambda 函数： + + ```bash + sam deploy --guided + + # Example: + + # Configuring SAM deploy + # ====================== + + # Looking for config file [samconfig.toml] : Not found + + # Setting default arguments for 'sam deploy' + # ========================================= + # Stack Name [sam-app]: tidb-aws-lambda-quickstart + # AWS Region [us-east-1]: + # #Shows you resources changes to be deployed and require a 'Y' to initiate deploy + # Confirm changes before deploy [y/N]: + # #SAM needs permission to be able to create roles to connect to the resources in your template + # Allow SAM CLI IAM role creation [Y/n]: + # #Preserves the state of previously provisioned resources when an operation fails + # Disable rollback [y/N]: + # tidbHelloWorldFunction may not have authorization defined, Is this okay? [y/N]: y + # tidbHelloWorldFunction may not have authorization defined, Is this okay? [y/N]: y + # tidbHelloWorldFunction may not have authorization defined, Is this okay? [y/N]: y + # tidbHelloWorldFunction may not have authorization defined, Is this okay? [y/N]: y + # Save arguments to configuration file [Y/n]: + # SAM configuration file [samconfig.toml]: + # SAM configuration environment [default]: + + # Looking for resources needed for deployment: + # Creating the required resources... + # Successfully created! + ``` + +### Web控制台部署 + +1. 构建应用程序包： + + ```bash + npm run build + + # Bundle for AWS Lambda + # ===================== + # dist/index.zip + ``` + +2. 访问 [AWS Lambda 控制台](https://console.aws.amazon.com/lambda/home#/functions). + +3. 按照 [使用 Node.js 构建 Lambda 函数](https://docs.aws.amazon.com/zh_cn/lambda/latest/dg/lambda-nodejs.html) 中的步骤创建一个Node.js Lambda函数。 + +4. 按照 [.zip 文件存档](https://docs.aws.amazon.com/zh_cn/lambda/latest/dg/gettingstarted-package.html#gettingstarted-package-zip) 中的步骤，上传dist/index.zip文件。 + +5. 在 Lambda 函数 中[复制和配置相应的连接字符串](https://docs.aws.amazon.com/zh_cn/lambda/latest/dg/configuration-envvars.html)。 + + 1. 在Lambda控制台的 [函数](https://console.aws.amazon.com/lambda/home#/functions) 页面中，选择**配置**选项卡，然后选择**环境变量**。 + 2. 选择**编辑**。 + 3. 添加数据库访问凭据，按照以下步骤进行操作： + + - 选择**添加环境变量**，然后在**键**中输入 `TIDB_HOST` ，在**值**中输入 主机名。 + - 选择**添加环境变量**，然后在**键**中输入 `TIDB_PORT` ，在**值**中输入 端口号（默认`4000`）。 + - 选择**添加环境变量**，然后在**键**中输入 `TIDB_USER` ，在**值**中输入 用户名。 + - 选择**添加环境变量**，然后在**键**中输入 `TIDB_PASSWORD` ，在**值**中输入 创建数据库时输入的密码。 + - 选择**保存** + +## 示例代码片段 + +你可参考以下关键代码片段，完成自己的应用开发。 + +整代码及其运行方式，见代码仓库 [tidb-samples/tidb-aws-lambda-quickstart](https://github.com/tidb-samples/tidb-aws-lambda-quickstart)。 + +### 连接到 TiDB + +以下代码使用环境变量中定义的选项建立与 TiDB 的连接： + +```typescript +// lib/tidb.ts +import mysql from 'mysql2'; + +let pool: mysql.Pool | null = null; + +function connect() { + return mysql.createPool({ + host: process.env.TIDB_HOST, // TiDB host, for example: {gateway-region}.aws.tidbcloud.com + port: process.env.TIDB_PORT ? Number(process.env.TIDB_PORT) : 4000, // TiDB port, default: 4000 + user: process.env.TIDB_USER, // TiDB user, for example: {prefix}.root + password: process.env.TIDB_PASSWORD, // TiDB password + database: process.env.TIDB_DATABASE || 'test', // TiDB database name, default: test + ssl: { + minVersion: 'TLSv1.2', + rejectUnauthorized: true, + }, + connectionLimit: 1, // Setting connectionLimit to "1" in a serverless function environment optimizes resource usage, reduces costs, ensures connection stability, and enables seamless scalability. + maxIdle: 1, // max idle connections, the default value is the same as `connectionLimit` + enableKeepAlive: true, + }); +} + +export function getPool(): mysql.Pool { + if (!pool) { + pool = connect(); + } + return pool; +} +``` + +### 插入数据 + +以下查询创建一个单独的 `Players` 记录并返回一个 `ResultSetHeader` 对象： + +```typescript +const [rsh] = await pool.query('INSERT INTO players (coins, goods) VALUES (?, ?);', [100, 100]); +console.log(rsh.insertId); +``` + +要了解更多信息，请参考 [插入数据](/develop/dev-guide-insert-data.md)。 + +### 查询数据 + +以下查询返回一个 `Players` 记录，其 ID 为 `1`： + +```typescript +const [rows] = await pool.query('SELECT id, coins, goods FROM players WHERE id = ?;', [1]); +console.log(rows[0]); +``` + +要了解更多信息，请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 + +### 更新数据 + +以下查询将 `50` 个硬币和 `50` 个商品添加到 `ID` 为 `1` 的 `Player` 中： + +```typescript +const [rsh] = await pool.query( + 'UPDATE players SET coins = coins + ?, goods = goods + ? WHERE id = ?;', + [50, 50, 1] +); +console.log(rsh.affectedRows); +``` + +要了解更多信息，请参考 [更新数据](/develop/dev-guide-update-data.md)。 + +### 删除数据 + +以下查询删除一个 `Players` 记录，其 ID 为 `1`： + +```typescript +const [rsh] = await pool.query('DELETE FROM players WHERE id = ?;', [1]); +console.log(rsh.affectedRows); +``` + +要了解更多信息，请参考 [删除数据](/develop/dev-guide-delete-data.md)。 + +## 注意事项 + +- 推荐使用[连接池](https://github.com/sidorares/node-mysql2#using-connection-pools)来管理数据库连接，以减少频繁建立和销毁连接所带来的性能开销。 +- 为了避免 SQL 注入的风险，推荐使用[预处理语句](https://github.com/sidorares/node-mysql2#using-prepared-statements)执行 SQL。 +- 在不涉及大量复杂 SQL 语句的场景下，推荐使用 ORM 框架 (例如：[Sequelize](https://sequelize.org/)、[TypeORM](https://typeorm.io/) 或 [Prisma](https://www.prisma.io/)) 来提升你的开发效率。 +- 为了为你的应用程序构建一个RESTful API，建议 [将 AWS Lambda 与 Amazon API Gateway 结合使用](https://docs.aws.amazon.com/zh_cn/lambda/latest/dg/services-apigateway.html)。 +- 要设计使用TiDB Serverless和AWS Lambda的高性能应用程序，请参考这篇[博客文章](https://aws.amazon.com/blogs/apn/designing-high-performance-applications-using-serverless-tidb-cloud-and-aws-lambda/)。 + +## 下一步 + +- 要了解如何在AWS Lambda函数中使用TiDB的更多细节，请参考我们的 [TiDB-Lambda-integration/aws-lambda-bookstore Demo](https://github.com/pingcap/TiDB-Lambda-integration/blob/main/aws-lambda-bookstore/README.md)。你也可以使用AWS API Gateway来构建你的应用程序的RESTful API。 +- 关于 node-mysql2 的更多使用方法，可以参考 [node-mysql2 的 GitHub 仓库](https://github.com/sidorares/node-mysql2)。 +- 从[AWS Lambda的开发者指南](https://docs.aws.amazon.com/zh_cn/lambda/latest/dg/welcome.html)中了解更多关于AWS Lambda的用法。 +- 你可以继续阅读开发者文档的其它章节来获取更多 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/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 + +## 需要帮助吗？ + +访问我们的 [支持资源](/support.md) 以寻求帮助。 diff --git a/markdown-pages/zh/tidb/release-7.5/develop/dev-guide-sample-application-nextjs.md b/markdown-pages/zh/tidb/release-7.5/develop/dev-guide-sample-application-nextjs.md new file mode 100644 index 00000000..573d2e01 --- /dev/null +++ b/markdown-pages/zh/tidb/release-7.5/develop/dev-guide-sample-application-nextjs.md @@ -0,0 +1,272 @@ +--- +title: 在 Next.js 中使用 mysql2 连接 TiDB +summary: 本文介绍了如何在 Next.js 中使用 TiDB 和 mysql2 构建一个 CRUD 应用程序，并提供了一个简单的代码示例。 +--- + +# 在 Next.js 中使用 mysql2 连接 TiDB + +TiDB 是一个兼容 MySQL 的数据库，[node-mysql2](https://github.com/sidorares/node-mysql2) 是一个与 [mysqljs/mysql](https://github.com/mysqljs/mysql) 兼容的面向 Node.js 的 MySQL 驱动，[Next.js](https://nextjs.org/) 是一个 React 框架，用于构建快速、可扩展的现代应用程序。 + +在本教程中，您将学习如何在 Next.js 中使用 TiDB 和 mysql2 来完成以下任务： + +- 配置你的环境。 +- 使用 node-mysql2 驱动连接到 TiDB 集群。 +- 构建并运行你的应用程序。你也可以参考[示例代码片段](#示例代码片段)，完成基本的 CRUD 操作。 + +> **注意** +> +> 本文档适用于 TiDB Serverless 和本地部署的 TiDB。 + +## 前置需求 + +为了能够顺利完成本教程，你需要提前： + +- 在你的机器上安装 [Node.js](https://nodejs.org/en) 18.x 或以上版本。 +- 在你的机器上安装 [Git](https://git-scm.com/downloads)。 +- 准备一个 TiDB 集群。 + +**如果你还没有 TiDB 集群，可以按照以下方式创建：** + +- （推荐方式）参考[创建 TiDB Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md#第-1-步创建-tidb-serverless-集群)，创建你自己的 TiDB Cloud 集群。 +- 参考[部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群)或[部署正式 TiDB 集群](/production-deployment-using-tiup.md)，创建本地集群。 + +## 运行代码并连接到 TiDB + +本小节演示如何运行示例应用程序的代码，并连接到 TiDB。 + +> **注意** +> +>要获取完整的代码片段和运行说明，请参考 [tidb-nextjs-vercel-quickstart](https://github.com/tidb-samples/tidb-nextjs-vercel-quickstart) GitHub存储库。 + +### 步骤 1：克隆示例应用程序仓库 + +在终端窗口中运行以下命令来克隆示例代码仓库： + +```bash +git clone git@github.com:tidb-samples/tidb-nextjs-vercel-quickstart.git +cd tidb-nextjs-vercel-quickstart +``` + +### 步骤 2：安装依赖 + +运行以下命令来安装示例应用程序所需的包（包括 mysql2 和 Next.js）： + +```bash +npm install +``` + +### 步骤 3：配置连接信息 + +根据您选择的 TiDB 部署选项，连接到您的 TiDB 集群。 + + + +
+ +1. 导航到 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，然后点击目标集群的名称，进入其概览页面。 + +2. 在右上角点击 **Connect**。将显示一个连接对话框。 + +3. 确认对话框中的选项配置和你的运行环境一致。 + + - **Endpoint Type** 为 `Public`。 + - **Branch** 选择 `main`。 + - **Connect With** 选择 `General`。 + - **Operating System** 为运行示例代码所在的操作系统。 + + > **Note** + > + > 在 Node.js 应用程序中，您无需提供 SSL CA 证书，因为在建立 TLS（SSL）连接时，默认情况下 Node.js 使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)。 + +4. 如果你还没有设置密码，点击 **Generate Password** 按钮生成一个随机的密码。 + + > **Tip** + > + > 如果您之前生成过密码，您可以使用原始密码，或者点击 **Reset Password** 来生成一个新密码。 + +5. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： + + ```bash + # Linux + cp .env.example .env + ``` + + ```powershell + # Windows + Copy-Item ".env.example" -Destination ".env" + ``` + +6. 编辑 `.env` 文件，按照如下格式设置环境变量 `DATABASE_URL`，将占位符 `{}` 替换为从连接对话框中复制的连接字符串： + + ```bash + TIDB_HOST='{gateway-region}.aws.tidbcloud.com' + TIDB_PORT='4000' + TIDB_USER='{prefix}.root' + TIDB_PASSWORD='{password}' + TIDB_DB_NAME='test' + ``` + +7. 保存 `.env` 文件。 + +
+ +
+ +1. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： + + ```bash + # Linux + cp .env.example .env + ``` + + ```powershell + # Windows + Copy-Item ".env.example" -Destination ".env" + ``` + +2. 编辑 `.env` 文件，按照如下格式设置环境变量 `DATABASE_URL`，将占位符 `{}` 替换为从连接对话框中复制的连接字符串： + + ```bash + TIDB_HOST='{tidb_server_host}' + TIDB_PORT='4000' + TIDB_USER='root' + TIDB_PASSWORD='{password}' + TIDB_DB_NAME='test' + ``` + + 如果您在本地运行 TiDB，则默认的主机地址是 `127.0.0.1`，密码为空。 + +3. 保存 `.env` 文件。 + +
+ + + +### 步骤 4：运行示例应用程序 + +1. 运行示例应用程序: + + ```bash + npm run dev + ``` + +2. 打开您的浏览器并访问 `http://localhost:3000`（请查看您的终端以获取实际的端口号，默认为`3000`）。 + +3. 点击**RUN SQL**以执行示例代码。 + +4. 在终端中检查输出。如果输出类似于以下内容，则连接成功： + + ```json + { + "results": [ + { + "Hello World": "Hello World" + } + ] + } + ``` + +## 示例代码片段 + +您可以参考以下示例代码片段来完成自己的应用程序开发。 + +要获取完整的示例代码和运行方式，请查看 [tidb-nextjs-vercel-quickstart](https://github.com/tidb-samples/tidb-nextjs-vercel-quickstart) 存储库。 + +### 连接到 TiDB + +以下代码使用环境变量中定义的选项建立与 TiDB 的连接： + +```javascript +// src/lib/tidb.js +import mysql from 'mysql2'; + +let pool = null; + +export function connect() { + return mysql.createPool({ + host: process.env.TIDB_HOST, // TiDB host, for example: {gateway-region}.aws.tidbcloud.com + port: process.env.TIDB_PORT || 4000, // TiDB port, default: 4000 + user: process.env.TIDB_USER, // TiDB user, for example: {prefix}.root + password: process.env.TIDB_PASSWORD, // The password of TiDB user. + database: process.env.TIDB_DATABASE || 'test', // TiDB database name, default: test + ssl: { + minVersion: 'TLSv1.2', + rejectUnauthorized: true, + }, + connectionLimit: 1, // Setting connectionLimit to "1" in a serverless function environment optimizes resource usage, reduces costs, ensures connection stability, and enables seamless scalability. + maxIdle: 1, // max idle connections, the default value is the same as `connectionLimit` + enableKeepAlive: true, + }); +} + +export function getPool() { + if (!pool) { + pool = createPool(); + } + return pool; +} +``` + +### 插入数据 + +以下查询创建一个单独的 `Players` 记录并返回一个 `ResultSetHeader` 对象： + +```javascript +const [rsh] = await pool.query('INSERT INTO players (coins, goods) VALUES (?, ?);', [100, 100]); +console.log(rsh.insertId); +``` + +要了解更多信息，请参考 [插入数据](/develop/dev-guide-insert-data.md)。 + +### 查询数据 + +以下查询返回一个 `Players` 记录，其 ID 为 `1`： + +```javascript +const [rows] = await pool.query('SELECT id, coins, goods FROM players WHERE id = ?;', [1]); +console.log(rows[0]); +``` + +要了解更多信息，请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 + +### 更新数据 + +以下查询将 `50` 个硬币和 `50` 个商品添加到 `ID` 为 `1` 的 `Player` 中： + +```javascript +const [rsh] = await pool.query( + 'UPDATE players SET coins = coins + ?, goods = goods + ? WHERE id = ?;', + [50, 50, 1] +); +console.log(rsh.affectedRows); +``` + +要了解更多信息，请参考 [更新数据](/develop/dev-guide-update-data.md)。 + +### 删除数据 + +以下查询删除一个 `Players` 记录，其 ID 为 `1`： + +```javascript +const [rsh] = await pool.query('DELETE FROM players WHERE id = ?;', [1]); +console.log(rsh.affectedRows); +``` + +要了解更多信息，请参考 [删除数据](/develop/dev-guide-delete-data.md)。 + +## 注意事项 + +- 推荐使用[连接池](https://github.com/sidorares/node-mysql2#using-connection-pools)来管理数据库连接，以减少频繁建立和销毁连接所带来的性能开销。 +- 为了避免 SQL 注入的风险，推荐使用[预处理语句](https://github.com/sidorares/node-mysql2#using-prepared-statements)执行 SQL。 +- 在不涉及大量复杂 SQL 语句的场景下，推荐使用 ORM 框架 (例如：[Sequelize](https://sequelize.org/)、[TypeORM](https://typeorm.io/) 或 [Prisma](https://www.prisma.io/)) 来提升你的开发效率。 + +## 下一步 + +- 要了解如何使用 ORM 和 Next.js 构建复杂应用程序的更多细节，请参阅我们的 [书店演示](https://github.com/pingcap/tidb-prisma-vercel-demo)。 +- 关于 node-mysql2 的更多使用方法，可以参考 [node-mysql2 的 GitHub 仓库](https://github.com/sidorares/node-mysql2)。 +- 你可以继续阅读开发者文档的其它章节来获取更多 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/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 + +## 需要帮助吗？ + +访问我们的 [支持资源](/support.md) 以寻求帮助。 diff --git a/markdown-pages/zh/tidb/release-7.5/develop/dev-guide-sample-application-nodejs-sequelize.md b/markdown-pages/zh/tidb/release-7.5/develop/dev-guide-sample-application-nodejs-sequelize.md new file mode 100644 index 00000000..08c08545 --- /dev/null +++ b/markdown-pages/zh/tidb/release-7.5/develop/dev-guide-sample-application-nodejs-sequelize.md @@ -0,0 +1,314 @@ +--- +title: 使用 Sequelize 连接到 TiDB +summary: 本文描述了 TiDB 和 Sequelize 的连接步骤，并给出了简单示例代码片段。 +--- + +# 使用 Sequelize 连接到 TiDB + +TiDB 是一个兼容 MySQL 的数据库。[Sequelize](https://sequelize.org/) 是当前流行的 Node.js ORM 框架之一。 + +本文档将展示如何使用 TiDB 和 Sequelize 来构造一个简单的 CRUD 应用程序。 + +- 配置你的环境。 +- 使用 Sequelize 连接到 TiDB 集群。 +- 构建并运行你的应用程序。你也可以参考[示例代码片段](#示例代码片段)，完成基本的 CRUD 操作。 + +> **注意** +> +> 本文档适用于 TiDB Serverless、TiDB Dedicated 和本地部署的 TiDB。 + +## 前置需求 + +为了能够顺利完成本教程，你需要提前： + +- 在你的机器上安装 [Node.js](https://nodejs.org/en) 18.x 或以上版本。 +- 在你的机器上安装 [Git](https://git-scm.com/downloads)。 +- 准备一个 TiDB 集群。 + +**如果您没有 TiDB 集群，可以按照以下步骤创建一个：** + +- （推荐）请按照 [创建 TiDB Serverless 集群](/develop/dev-guide-build-cluster-in-cloud.md) 的指引，创建您自己的 TiDB Cloud 集群。 +- 按照 [部署本地测试 TiDB 集群](/quick-start-with-tidb.md#部署本地测试集群) 或 [部署生产 TiDB 集群](/production-deployment-using-tiup.md) 的指引，创建一个本地集群。 + +## 运行示例应用程序并连接到 TiDB + +本节演示如何运行示例应用程序代码并连接到 TiDB。 + +> **注意** +> +> 完整的代码片段和运行说明，请参考 [tidb-samples/tidb-nodejs-sequelize-quickstart](https://github.com/tidb-samples/tidb-nodejs-sequelize-quickstart) GitHub 仓库。 + +### 步骤 1：克隆示例应用程序仓库 + +在终端窗口中运行以下命令来克隆示例代码仓库： + +```bash +git clone git@github.com:tidb-samples/tidb-nodejs-sequelize-quickstart.git +cd tidb-nodejs-sequelize-quickstart +``` + +### 步骤 2：安装依赖 + +运行以下命令来安装示例应用程序所需的包（包括 sequelize）： + +```bash +npm install +``` + +### 步骤 3：配置连接信息 + +根据您选择的 TiDB 部署选项，连接到您的 TiDB 集群。 + + + +
+ +1. 导航到 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，然后点击目标集群的名称，进入其概览页面。 + +2. 在右上角点击 **Connect**。将显示一个连接对话框。 + +3. 确认对话框中的选项配置和你的运行环境一致。 + + - **Endpoint Type** 为 `Public`。 + - **Branch** 选择 `main`。 + - **Connect With** 选择 `General`。 + - **Operating System** 为运行示例代码所在的操作系统。 + + > **Note** + > + > 在 Node.js 应用程序中，您无需提供 SSL CA 证书，因为在建立 TLS（SSL）连接时，默认情况下 Node.js 使用内置的 [Mozilla CA 证书](https://wiki.mozilla.org/CA/Included_Certificates)。 + +4. 如果你还没有设置密码，点击 **Generate Password** 按钮生成一个随机的密码。 + + > **Tip** + > + > 如果您之前生成过密码，您可以使用原始密码，或者点击 **Reset Password** 来生成一个新密码。 + +5. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： + + ```bash + cp .env.example .env + ``` + +6. 编辑 `.env` 文件，按照如下格式设置环境变量 `DATABASE_URL`，将占位符 `{}` 替换为从连接对话框中复制的连接字符串： + + ```dotenv + TIDB_HOST='{host}' + TIDB_PORT='4000' + TIDB_USER='{user}' + TIDB_PASSWORD='{password}' + TIDB_DB_NAME='test' + TIDB_ENABLE_SSL='true' + ``` + +7. 保存 `.env` 文件。 + +
+ +
+ +1. 导航到 [**Clusters**](https://tidbcloud.com/console/clusters) 页面，然后点击目标集群的名称，进入其概览页面。 + +2. 在右上角点击 **Connect**。将显示一个连接对话框。 + +3. 点击 **Allow Access from Anywhere**，然后点击 **Download TiDB cluster CA** 来下载 CA 证书。 + + 要了解更多关于如何获取连接字符串的详细信息，请参考 [TiDB Dedicated 标准连接](https://docs.pingcap.com/tidbcloud/connect-via-standard-connection)。 + +4. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： + + ```bash + cp .env.example .env + ``` + +5. 编辑 `.env` 文件，按照如下格式设置环境变量 `DATABASE_URL`，将占位符 `{}` 替换为从连接对话框中复制的连接字符串： + + ```shell + TIDB_HOST='{host}' + TIDB_PORT='4000' + TIDB_USER='{user}' + TIDB_PASSWORD='{password}' + TIDB_DB_NAME='test' + TIDB_ENABLE_SSL='true' + TIDB_CA_PATH='{path/to/ca}' + ``` + +6. 保存 `.env` 文件。 + +
+ +
+ +1. 运行以下命令，将 `.env.example` 复制并重命名为 `.env`： + + ```bash + cp .env.example .env + ``` + +2. 编辑 `.env` 文件，按照如下格式设置环境变量 `DATABASE_URL`，将占位符 `{}` 替换为从连接对话框中复制的连接字符串： + + ```shell + TIDB_HOST='{host}' + TIDB_PORT='4000' + TIDB_USER='root' + TIDB_PASSWORD='{password}' + TIDB_DB_NAME='test' + ``` + + 如果您在本地运行 TiDB，则默认的主机地址是 `127.0.0.1`，密码为空。 + +3. 保存 `.env` 文件。 + +
+ + + +### 步骤 4：运行示例应用程序 + +运行以下命令来执行示例代码： + +```shell +npm start +``` + +
+**预期输出（部分）：** + +```shell +INFO (app/10117): Getting sequelize instance... +Executing (default): SELECT 1+1 AS result +Executing (default): DROP TABLE IF EXISTS `players`; +Executing (default): CREATE TABLE IF NOT EXISTS `players` (`id` INTEGER NOT NULL auto_increment COMMENT 'The unique ID of the player.', `coins` INTEGER NOT NULL COMMENT 'The number of coins that the player had.', `goods` INTEGER NOT NULL COMMENT 'The number of goods that the player had.', `createdAt` DATETIME NOT NULL, `updatedAt` DATETIME NOT NULL, PRIMARY KEY (`id`)) ENGINE=InnoDB; +Executing (default): SHOW INDEX FROM `players` +Executing (default): INSERT INTO `players` (`id`,`coins`,`goods`,`createdAt`,`updatedAt`) VALUES (1,100,100,'2023-08-31 09:10:11','2023-08-31 09:10:11'),(2,200,200,'2023-08-31 09:10:11','2023-08-31 09:10:11'),(3,300,300,'2023-08-31 09:10:11','2023-08-31 09:10:11'),(4,400,400,'2023-08-31 09:10:11','2023-08-31 09:10:11'),(5,500,500,'2023-08-31 09:10:11','2023-08-31 09:10:11'); +Executing (default): SELECT `id`, `coins`, `goods`, `createdAt`, `updatedAt` FROM `players` AS `players` WHERE `players`.`coins` > 300; +Executing (default): UPDATE `players` SET `coins`=?,`goods`=?,`updatedAt`=? WHERE `id` = ? +Executing (default): DELETE FROM `players` WHERE `id` = 6 +``` + +
+ +## 示例代码片段 + +你可参考以下关键代码片段，完成自己的应用开发。 + +完整代码及其运行方式，见代码仓库 [tidb-samples/tidb-nodejs-sequelize-quickstart](https://github.com/tidb-samples/tidb-nodejs-sequelize-quickstart)。 + +### 连接到 TiDB + +以下代码使用环境变量中定义的选项建立与 TiDB 的连接： + +```typescript +// src/lib/tidb.ts +import { Sequelize } from 'sequelize'; + +export function initSequelize() { + return new Sequelize({ + dialect: 'mysql', + host: process.env.TIDB_HOST || 'localhost', // TiDB host, for example: {gateway-region}.aws.tidbcloud.com + port: Number(process.env.TIDB_PORT) || 4000, // TiDB port, default: 4000 + username: process.env.TIDB_USER || 'root', // TiDB user, for example: {prefix}.root + password: process.env.TIDB_PASSWORD || 'root', // TiDB password + database: process.env.TIDB_DB_NAME || 'test', // TiDB database name, default: test + dialectOptions: { + ssl: + process.env?.TIDB_ENABLE_SSL === 'true' // (Optional) Enable SSL + ? { + minVersion: 'TLSv1.2', + rejectUnauthorized: true, + ca: process.env.TIDB_CA_PATH // (Optional) Path to the custom CA certificate + ? readFileSync(process.env.TIDB_CA_PATH) + : undefined, + } + : null, + }, +} + +export async function getSequelize() { + if (!sequelize) { + sequelize = initSequelize(); + try { + await sequelize.authenticate(); + logger.info('Connection has been established successfully.'); + } catch (error) { + logger.error('Unable to connect to the database:'); + logger.error(error); + throw error; + } + } + return sequelize; +} +``` + +### 插入数据 + +以下查询创建一个单独的 `Players` 记录并返回一个 `Players` 对象： + +```typescript +logger.info('Creating a new player...'); +const newPlayer = await playersModel.create({ + id: 6, + coins: 600, + goods: 600, +}); +logger.info('Created a new player.'); +logger.info(newPlayer.toJSON()); +``` + +要了解更多信息，请参考 [插入数据](/develop/dev-guide-insert-data.md)。 + +### 查询数据 + +以下查询返回一个 `Players` 记录，其金币数量大于 `300`： + +```typescript +logger.info('Reading all players with coins > 300...'); +const allPlayersWithCoinsGreaterThan300 = await playersModel.findAll({ + where: { + coins: { + [Op.gt]: 300, + }, + }, +}); +logger.info('Read all players with coins > 300.'); +logger.info(allPlayersWithCoinsGreaterThan300.map((p) => p.toJSON())); +``` + +要了解更多信息，请参考 [查询数据](/develop/dev-guide-get-data-from-single-table.md)。 + +### 更新数据 + +以下查询将 `ID` 为 `6` 的 `Players` 的金币数量和物品数量设置为 `700`，这个记录是在 [插入数据](#插入数据) 部分创建的： + +```typescript +logger.info('Updating the new player...'); +await newPlayer.update({ coins: 700, goods: 700 }); +logger.info('Updated the new player.'); +logger.info(newPlayer.toJSON()); +``` + +要了解更多信息，请参考 [更新数据](/develop/dev-guide-update-data.md)。 + +### 删除数据 + +以下查询删除了在 [插入数据](#插入数据) 部分创建的 `Player` 记录，其 `ID` 为 `6`： + +```typescript +logger.info('Deleting the new player...'); +await newPlayer.destroy(); +const deletedNewPlayer = await playersModel.findByPk(6); +logger.info('Deleted the new player.'); +logger.info(deletedNewPlayer?.toJSON()); +``` + +要了解更多信息，请参考 [删除数据](/develop/dev-guide-delete-data.md)。 + +## 下一步 + +- 从 [Sequelize的文档](https://sequelize.org/) 中了解更多关于ORM框架Sequelize驱动程序的用法。 +- 你可以继续阅读开发者文档的其它章节来获取更多 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/category/back-end-developer/?utm_source=docs-cn-dev-guide)支持，并在考试后提供相应的[资格认证](https://learn.pingcap.com/learner/certification-center)。 + +## 需要帮助吗？ + +访问我们的 [支持资源](/support.md) 以寻求帮助。