使用 Sequelize 连接到 TiDB
TiDB 是一个兼容 MySQL 的数据库。Sequelize 是当前流行的 Node.js ORM 框架之一。
本文档将展示如何使用 TiDB 和 Sequelize 来构造一个简单的 CRUD 应用程序。
- 配置你的环境。
- 使用 Sequelize 连接到 TiDB 集群。
- 构建并运行你的应用程序。你也可以参考示例代码片段，完成基本的 CRUD 操作。
前置需求
为了能够顺利完成本教程，你需要提前：
如果你还没有 TiDB 集群，可以按照以下方式创建：
- （推荐方式）参考创建 TiDB Serverless 集群，创建你自己的 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 集群。
- TiDB Serverless
- TiDB Dedicated
- 本地部署的 TiDB
在 TiDB Cloud 的 Clusters 页面中，选择你的 TiDB Serverless 集群，进入集群的 Overview 页面。
点击右上角的 Connect 按钮，将会弹出连接对话框。
确认对话框中的选项配置和你的运行环境一致。
- Connection Type 为
Public。 - Branch 选择
main。 - Connect With 选择
General。 - Operating System 为运行示例代码所在的操作系统。
- Connection Type 为
如果你还没有设置密码，点击 Generate Password 按钮生成一个随机的密码。
运行以下命令，将
.env.example复制并重命名为.env：cp .env.example .env编辑
.env文件，按照如下格式设置连接信息，将占位符{}替换为从连接对话框中复制的参数值：TIDB_HOST='{host}' TIDB_PORT='4000' TIDB_USER='{user}' TIDB_PASSWORD='{password}' TIDB_DB_NAME='test' TIDB_ENABLE_SSL='true'保存
.env文件。
在 TiDB Cloud 的 Clusters 页面中，选择你的 TiDB Dedicated 集群，进入集群的 Overview 页面。
点击右上角的 Connect 按钮，将会出现连接对话框。
在连接对话框中，从 Connection Type 下拉列表中选择 Public，并点击 CA cert 下载 CA 文件。
如果你尚未配置 IP 访问列表，请在首次连接前点击 Configure IP Access List 或按照配置 IP 访问列表（英文）中的步骤进行配置。
除 Public 连接类型外，TiDB Dedicated 还支持 Private Endpoint 和 VPC Peering 连接类型。详情请参阅连接 TiDB Dedicated 集群（英文）。
运行以下命令，将
.env.example复制并重命名为.env：cp .env.example .env编辑
.env文件，按照如下格式设置连接信息，将占位符{}替换为从连接对话框中复制的参数值：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}'保存
.env文件。
运行以下命令，将
.env.example复制并重命名为.env：cp .env.example .env编辑
.env文件，按照如下格式设置连接信息，将占位符{}替换为你的 TiDB 集群的连接参数值：TIDB_HOST='{host}' TIDB_PORT='4000' TIDB_USER='root' TIDB_PASSWORD='{password}' TIDB_DB_NAME='test'如果你在本地运行 TiDB 集群，默认的主机地址是
127.0.0.1，密码为空。保存
.env文件。
第 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());
更多信息参考插入数据。
查询数据
下面的查询会返回一条 Players 记录，其金币数量大于 300：
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 的 Player 的金币数量和物品数量设置为 700，这个记录是在插入数据部分创建的：
logger.info('Updating the new player...');
await newPlayer.update({ coins: 700, goods: 700 });
logger.info('Updated the new player.');
logger.info(newPlayer.toJSON());
更多信息参考更新数据。
删除数据
下面的查询会删除在插入数据部分创建的 Player 记录，其 ID 为 6：
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 的更多使用方法，可以参考 Sequelize 的官方文档。
- 你可以继续阅读开发者文档的其它章节来获取更多 TiDB 应用开发的最佳实践。例如：插入数据，更新数据，删除数据，单表读取，事务，SQL 性能优化等。
- 如果你更倾向于参与课程进行学习，我们也提供专业的 TiDB 开发者课程支持，并在考试后提供相应的资格认证。