From 06bc52a5ecfa237533c6ed823de619c43e04a890 Mon Sep 17 00:00:00 2001 From: Ti Chi Robot Date: Fri, 27 Oct 2023 11:48:35 +0800 Subject: [PATCH] develop guide: add sample applications - sequelize (#14705) (#14922) --- TOC-tidb-cloud.md | 1 + TOC.md | 1 + ...ide-sample-application-nodejs-sequelize.md | 325 ++++++++++++++++++ 3 files changed, 327 insertions(+) create mode 100644 develop/dev-guide-sample-application-nodejs-sequelize.md diff --git a/TOC-tidb-cloud.md b/TOC-tidb-cloud.md index e1b84a39fa000..71b3d354078dc 100644 --- a/TOC-tidb-cloud.md +++ b/TOC-tidb-cloud.md @@ -43,6 +43,7 @@ - [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) diff --git a/TOC.md b/TOC.md index 8344629fae33f..2e483f1abc037 100644 --- a/TOC.md +++ b/TOC.md @@ -41,6 +41,7 @@ - [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) diff --git a/develop/dev-guide-sample-application-nodejs-sequelize.md b/develop/dev-guide-sample-application-nodejs-sequelize.md new file mode 100644 index 0000000000000..c4c905fe75185 --- /dev/null +++ b/develop/dev-guide-sample-application-nodejs-sequelize.md @@ -0,0 +1,325 @@ +--- +title: Connect to TiDB with Sequelize +summary: Learn how to connect to TiDB using Sequelize. This tutorial gives Node.js sample code snippets that work with TiDB using Sequelize. +--- + +# Connect to TiDB with Sequelize + +TiDB is a MySQL-compatible database, and [Sequelize](https://sequelize.org/) is a popular ORM framework for Node.js. + +In this tutorial, you can learn how to use TiDB and Sequelize to accomplish the following tasks: + +- Set up your environment. +- Connect to your TiDB cluster using Sequelize. +- Build and run your application. Optionally, you can find [sample code snippets](#sample-code-snippets) for basic CRUD operations. + +> **Note** +> +> This tutorial works with TiDB Serverless, TiDB Dedicated, and TiDB Self-Hosted. + +## Prerequisites + +To complete this tutorial, you need: + +- [Node.js **18**](https://nodejs.org/en/download/) or later. +- [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](/develop/dev-guide-build-cluster-in-cloud.md) to create your own TiDB Cloud cluster. +- Follow [Deploy a local test TiDB cluster](/quick-start-with-tidb.md#deploy-a-local-test-cluster) or [Deploy a production TiDB cluster](/production-deployment-using-tiup.md) to create a local cluster. + + + + +**If you don't have a TiDB cluster, you can create one as follows:** + +- (Recommended) Follow [Creating a TiDB Serverless cluster](/develop/dev-guide-build-cluster-in-cloud.md) 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. + + + +## Run the sample app to connect to TiDB + +This section demonstrates how to run the sample application code and connect to TiDB. + +> **Note** +> +> For complete code snippets and running instructions, refer to the [tidb-samples/tidb-nodejs-sequelize-quickstart](https://github.com/tidb-samples/tidb-nodejs-sequelize-quickstart) GitHub repository. + +### Step 1: Clone the sample app repository + +Run the following commands in your terminal window to clone the sample code repository: + +```bash +git clone git@github.com:tidb-samples/tidb-nodejs-sequelize-quickstart.git +cd tidb-nodejs-sequelize-quickstart +``` + +### Step 2: Install dependencies + +Run the following command to install the required packages (including `sequelize`) for the sample app: + +```bash +npm install +``` + +### Step 3: Configure connection information + +Connect to your TiDB cluster depending on the TiDB deployment option you've selected. + + + +
+ +1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. + +2. Click **Connect** in the upper-right corner. A connection dialog is displayed. + +3. Ensure the configurations in the connection dialog match your operating environment. + + - **Endpoint Type** is set to `Public` + - **Connect With** is set to `General` + - **Operating System** matches your environment. + + > **Note** + > + > In Node.js applications, you don't have to provide an SSL CA certificate, because Node.js uses the built-in [Mozilla CA certificate](https://wiki.mozilla.org/CA/Included_Certificates) by default when establishing the TLS (SSL) connection. + +4. Click **Create password** to create a random password. + + > **Tip** + > + > If you have generated a password before, you can either use the original password or click **Reset password** to generate a new one. + +5. Run the following command to copy `.env.example` and rename it to `.env`: + + ```shell + cp .env.example .env + ``` + +6. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: + + ```dotenv + TIDB_HOST='{host}' + TIDB_PORT='4000' + TIDB_USER='{user}' + TIDB_PASSWORD='{password}' + TIDB_DB_NAME='test' + TIDB_ENABLE_SSL='true' + ``` + +7. Save the `.env` file. + +
+ +
+ +1. Navigate to the [**Clusters**](https://tidbcloud.com/console/clusters) page, and then click the name of your target cluster to go to its overview page. + +2. Click **Connect** in the upper-right corner. A connection dialog is displayed. + +3. Click **Allow Access from Anywhere** and then click **Download TiDB cluster CA** to download the CA certificate. + + For more details about how to obtain the connection string, refer to [TiDB Dedicated standard connection](https://docs.pingcap.com/tidbcloud/connect-via-standard-connection). + +4. Run the following command to copy `.env.example` and rename it to `.env`: + + ```shell + cp .env.example .env + ``` + +5. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: + + ```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. Save the `.env` file. + +
+ +
+ +1. Run the following command to copy `.env.example` and rename it to `.env`: + + ```shell + cp .env.example .env + ``` + +2. Edit the `.env` file, set up the environment variables as follows, replace the corresponding placeholders `{}` with connection parameters on the connection dialog: + + ```shell + TIDB_HOST='{host}' + TIDB_PORT='4000' + TIDB_USER='root' + TIDB_PASSWORD='{password}' + TIDB_DB_NAME='test' + ``` + + 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. + +
+ + + +### Step 4: Run the sample app + +Run the following command to execute the sample code: + +```shell +npm start +``` + +
+**Expected output(partial):** + +```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 +``` + +
+ +## Sample code snippets + +You can refer to the following sample code snippets to complete your own application development. + +For complete sample code and how to run it, check out the [tidb-samples/tidb-nodejs-sequelize-quickstart](https://github.com/tidb-samples/tidb-nodejs-sequelize-quickstart) repository. + +### Connect to TiDB + +The following code establish a connection to TiDB with options defined in the environment variables: + +```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; +} +``` + +### Insert data + +The following query creates a single `Players` record and returns a `Players` object: + +```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()); +``` + +For more information, refer to [Insert data](/develop/dev-guide-insert-data.md). + +### Query data + +The following query returns a single `Players` record those coins are greater than `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())); +``` + +For more information, refer to [Query data](/develop/dev-guide-get-data-from-single-table.md). + +### Update data + +The following query set `700` coins and `700` goods to the `Players` with ID `6` that was created in the [Insert data](#insert-data) section: + +```typescript +logger.info('Updating the new player...'); +await newPlayer.update({ coins: 700, goods: 700 }); +logger.info('Updated the new player.'); +logger.info(newPlayer.toJSON()); +``` + +For more information, refer to [Update data](/develop/dev-guide-update-data.md). + +### Delete data + +The following query deletes the `Player` record with ID `6` that was created in the [Insert data](#insert-data) section: + +```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()); +``` + +For more information, refer to [Delete data](/develop/dev-guide-delete-data.md). + +## Next steps + +- Learn more usage of the ORM framework Sequelize driver from [the documentation of Sequelize](https://sequelize.org/). +- Learn the best practices for TiDB application development with the chapters in the [Developer guide](/develop/dev-guide-overview.md), such as [Insert data](/develop/dev-guide-insert-data.md), [Update data](/develop/dev-guide-update-data.md), [Delete data](/develop/dev-guide-delete-data.md), [Single table reading](/develop/dev-guide-get-data-from-single-table.md), [Transactions](/develop/dev-guide-transaction-overview.md), and [SQL performance optimization](/develop/dev-guide-optimize-sql-overview.md). +- Learn through the professional [TiDB developer courses](https://www.pingcap.com/education/) and earn [TiDB certifications](https://www.pingcap.com/education/certification/) after passing the exam. + +## Need help? + +Ask questions on the [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc), or [create a support ticket](https://support.pingcap.com/).