使用 Sequelize 连接 TiDB

TiDB 是兼容 MySQL 的数据库，Sequelize 是 Node.js 中流行的 ORM 框架。

在本教程中，你可以学习如何使用 TiDB 和 Sequelize 完成以下任务：

• 搭建你的开发环境。
• 使用 Sequelize 连接到你的 TiDB 集群。
• 构建并运行你的应用程序。你还可以在 示例代码片段 中找到基本 CRUD 操作的代码示例。

前置条件

完成本教程，你需要：

• Node.js 18 或更高版本
• Git
• 一个 TiDB 集群

如果你还没有 TiDB 集群，可以按如下方式创建：

• （推荐）参考 创建 TiDB Cloud Starter 集群 创建你自己的 TiDB Cloud 集群。
• 参考 部署本地测试 TiDB 集群 或 部署生产环境 TiDB 集群 创建本地集群。

运行示例应用连接 TiDB

本节演示如何运行示例应用代码并连接到 TiDB。

步骤 1：克隆示例应用仓库

在终端窗口中运行以下命令，克隆示例代码仓库：

git clone git@github.com:tidb-samples/tidb-nodejs-sequelize-quickstart.git
cd tidb-nodejs-sequelize-quickstart

步骤 2：安装依赖

运行以下命令，为示例应用安装所需的依赖包（包括 sequelize）：

npm install

步骤 3：配置连接信息

根据你选择的 TiDB 部署方式，连接到你的 TiDB 集群。

步骤 4：运行示例应用

运行以下命令执行示例代码：

npm start

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 仓库。

连接 TiDB

以下代码通过环境变量定义的参数建立 TiDB 连接：

// 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 对象：

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());

更多信息请参考 插入数据。

查询数据

以下查询会返回所有 coins 大于 300 的 Players 记录：

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()));

更多信息请参考 查询数据。

更新数据

以下查询会将 插入数据 部分创建的 ID 为 6 的 Players 的 coins 和 goods 更新为 700：

logger.info('Updating the new player...');
await newPlayer.update({ coins: 700, goods: 700 });
logger.info('Updated the new player.');
logger.info(newPlayer.toJSON());

更多信息请参考 更新数据。

删除数据

以下查询会删除 插入数据 部分创建的 ID 为 6 的 Player 记录：

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());

更多信息请参考 删除数据。

后续步骤

• 通过 Sequelize 官方文档 学习更多 ORM 框架 Sequelize 的用法。
• 通过 开发者指南 各章节，学习 TiDB 应用开发最佳实践，例如 插入数据、更新数据、删除数据、单表读取、事务 以及 SQL 性能优化。
• 通过专业的 TiDB 开发者课程 学习，并在通过考试后获得 TiDB 认证。

需要帮助？

欢迎在 Discord 或 Slack 社区提问，或 提交支持工单。