使用 Prisma 连接到 TiDB
TiDB 是一个兼容 MySQL 的数据库。Prisma 是当前流行的 Node.js ORM 框架之一。
本文档将展示如何使用 TiDB 和 Prisma 来构造一个简单的 CRUD 应用程序。
- 配置你的环境。
- 使用 Prisma 连接到 TiDB 集群。
- 构建并运行你的应用程序。你也可以参考示例代码片段,完成基本的 CRUD 操作。
前置需求
为了能够顺利完成本教程,你需要提前:
如果你还没有 TiDB 集群,可以按照以下方式创建:
- (推荐方式)参考创建 TiDB Serverless 集群,创建你自己的 TiDB Cloud 集群。
- 参考部署本地测试 TiDB 集群或部署正式 TiDB 集群,创建本地集群。
运行代码并连接到 TiDB
本小节演示如何运行示例应用程序的代码,并连接到 TiDB。
第 1 步:克隆示例代码仓库到本地
运行以下命令,将示例代码仓库克隆到本地:
git clone https://github.com/tidb-samples/tidb-nodejs-prisma-quickstart.git
cd tidb-nodejs-prisma-quickstart
第 2 步:安装依赖
运行以下命令,安装示例代码所需要的依赖 (包括 prisma
依赖包):
npm install
在你现有的项目当中,你可以通过以下命令安装所需要的依赖包:
npm install prisma typescript ts-node @types/node --save-dev
第 3 步:配置连接信息
根据不同的 TiDB 部署方式,使用不同的方法连接到 TiDB 集群。
- TiDB Serverless
- TiDB Dedicated
- 本地部署的 TiDB
在 TiDB Cloud 的 Clusters 页面中,选择你的 TiDB Serverless 集群,进入集群的 Overview 页面。
点击右上角的 Connect 按钮,将会弹出连接对话框。
确认对话框中的选项配置和你的运行环境一致。
- Connection Type 为
Public
。 - Branch 选择
main
。 - Connect With 选择
Prisma
。 - Operating System 为运行示例代码所在的操作系统。
- Connection Type 为
如果你还没有设置密码,点击 Generate Password 按钮生成一个随机的密码。
运行以下命令,将
.env.example
复制并重命名为.env
:cp .env.example .env编辑
.env
文件,按照如下格式设置环境变量DATABASE_URL
,将占位符{}
替换为从连接对话框中复制的连接字符串:DATABASE_URL='{connection_string}'保存
.env
文件。在
prisma/schema.prisma
文件中,将provider
修改为mysql
,并将url
修改为env("DATABASE_URL")
:datasource db { provider = "mysql" url = env("DATABASE_URL") }
在 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
文件,按照如下格式设置环境变量DATABASE_URL
,将占位符{}
替换为从连接对话框中复制的参数值:DATABASE_URL='mysql://{user}:{password}@{host}:4000/test?sslaccept=strict&sslcert={downloaded_ssl_ca_path}'保存
.env
文件。在
prisma/schema.prisma
文件中,将provider
修改为mysql
,并将url
修改为env("DATABASE_URL")
:datasource db { provider = "mysql" url = env("DATABASE_URL") }
运行以下命令,将
.env.example
复制并重命名为.env
:cp .env.example .env编辑
.env
文件,按照如下格式设置连接信息,将占位符{}
替换为你的 TiDB 集群的连接参数值:DATABASE_URL='mysql://{user}:{password}@{host}:4000/test'如果你在本地运行 TiDB 集群,默认的 Host 是
127.0.0.1
, 默认用户名为root
, 密码为空。保存
.env
文件。在
prisma/schema.prisma
文件中,将provider
修改为mysql
,并将url
修改为env("DATABASE_URL")
:datasource db { provider = "mysql" url = env("DATABASE_URL") }
第 4 步:初始化表结构
运行以下命令,使用 Prisma Migrate 根据 prisma/schema.prisma
文件中的数据模型定义来初始化数据库表结构:
npx prisma migrate dev
prisma.schema
文件中的模型定义:
// 定义一个 Player 模型,表示 `players` 表。
model Player {
id Int @id @default(autoincrement())
name String @unique(map: "uk_player_on_name") @db.VarChar(50)
coins Decimal @default(0)
goods Int @default(0)
createdAt DateTime @default(now()) @map("created_at")
profile Profile?
@@map("players")
}
// 定义一个 Profile 模型,表示 `profiles` 表。
model Profile {
playerId Int @id @map("player_id")
biography String @db.Text
// 定义 `Player` 和 `Profile` 模型之间的 1:1 关系,并使用外键约束。
player Player @relation(fields: [playerId], references: [id], onDelete: Cascade, map: "fk_profile_on_player_id")
@@map("profiles")
}
你可以通过查阅 Prisma 的 Data model 文档来了解如何在 prisma.schema
文件里定义数据模型。
预期执行结果:
Your database is now in sync with your schema.
✔ Generated Prisma Client (5.1.1 | library) to ./node_modules/@prisma/client in 54ms
这个命令同时会根据 prisma/schema.prisma
文件中的模型定义,生成用于与数据库交互的 Prisma Client 的代码。
第 5 步:运行代码并查看结果
运行下述命令,执行示例代码:
npm start
示例代码中的主要逻辑:
// 步骤 1. 导入自动生成的 `@prisma/client` 依赖包。
import {Player, PrismaClient} from '@prisma/client';
async function main(): Promise<void> {
// 步骤 2. 创建一个新的 `PrismaClient` 实例。
const prisma = new PrismaClient();
try {
// 步骤 3. 使用 Prisma Client 执行一些 CRUD 操作。
} finally {
// 步骤 4. 断开 Prisma Client 的连接。
await prisma.$disconnect();
}
}
void main();
预期输出结果:
如果连接成功,在你的终端上会输出所连接集群的版本信息。
🔌 Connected to TiDB cluster! (TiDB version: 5.7.25-TiDB-v6.6.0-serverless)
🆕 Created a new player with ID 1.
ℹ️ Got Player 1: Player { id: 1, coins: 100, goods: 100 }
🔢 Added 50 coins and 50 goods to player 1, now player 1 has 150 coins and 150 goods.
🚮 Player 1 has been deleted.
示例代码片段
你可参考以下关键代码片段,完成自己的应用开发。
完整代码及其运行方式,见代码仓库 tidb-samples/tidb-nodejs-prisma-quickstart。
插入数据
下面的查询会创建一条新的 Player
记录,并返回一个包含自增 ID 的 Player
对象:
const player: Player = await prisma.player.create({
data: {
name: 'Alice',
coins: 100,
goods: 200,
createdAt: new Date(),
}
});
console.log(player.id);
更多信息参考插入数据。
查询数据
下面的查询会返回 ID 为 101
的 Player
记录,如果没有找到对应的记录,会返回 null
:
const player: Player | null = prisma.player.findUnique({
where: {
id: 101,
}
});
更多信息参考查询数据。
更新数据
下面的查询会将 ID 为 101
的 Player
记录的 coins
和 goods
字段的值分别增加 50:
await prisma.player.update({
where: {
id: 101,
},
data: {
coins: {
increment: 50,
},
goods: {
increment: 50,
},
}
});
更多信息参考更新数据。
删除数据
下面的查询会删除 ID 为 101
的 Player
记录:
await prisma.player.delete({
where: {
id: 101,
}
});
更多信息参考删除数据。
注意事项
外键约束与 Prisma Relation Mode
你可以使用外键约束或 Prisma Relation Mode 来检查参照完整性:
外键是 TiDB 从 v6.6.0 开始支持的实验特性,外键允许跨表交叉引用相关数据,外键约束则可以保证相关数据的一致性。
Prisma Relation Mode 是 Prisma Client 端对外键约束的模拟。该特性会对应用程序的性能产生一些影响,因为它需要额外的数据库查询来维护参照完整性。
下一步
- 关于 Prisma 的更多使用方法,可以参考 Prisma 的官方文档。
- 你可以继续阅读开发者文档的其它章节来获取更多 TiDB 应用开发的最佳实践。例如:插入数据,更新数据,删除数据,单表读取,事务,SQL 性能优化等。
- 如果你更倾向于参与课程进行学习,我们也提供专业的 TiDB 开发者课程支持,并在考试后提供相应的资格认证。