使用 Prisma 连接到 TiDB

TiDB 是一个兼容 MySQL 的数据库。Prisma 是当前流行的 Node.js ORM 框架之一。

本文档将展示如何使用 TiDB 和 Prisma 来构造一个简单的 CRUD 应用程序。

• 配置你的环境。
• 使用 Prisma 连接到 TiDB 集群。
• 构建并运行你的应用程序。你也可以参考示例代码片段，完成基本的 CRUD 操作。

前置需求

为了能够顺利完成本教程，你需要提前：

• 在你的机器上安装 Node.js 16.x 或以上版本。
• 在你的机器上安装 Git。
• 准备一个 TiDB 集群。

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

• （推荐方式）参考创建 TiDB Cloud 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 Cloud Serverless
• TiDB Cloud Dedicated
• 本地部署的 TiDB

第 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: 8.0.11-TiDB-v8.5.0)
🆕 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 来检查参照完整性：

• 外键是从 v6.6.0 开始支持的，在 v8.5.0 成为正式功能。外键允许跨表交叉引用相关数据，外键约束则可以保证相关数据的一致性。

  警告

  外键功能通常适用于为中小规模的数据提供完整性和一致性约束校验，但是在大数据量和分布式数据库系统下，使用外键可能会导致严重的性能问题，并对系统产生不可预知的影响。如果计划使用外键，请进行充分验证后谨慎使用。

• Prisma Relation Mode 是 Prisma Client 端对外键约束的模拟。该特性会对应用程序的性能产生一些影响，因为它需要额外的数据库查询来维护参照完整性。

下一步

• 关于 Prisma 的更多使用方法，可以参考 Prisma 的官方文档。
• 你可以继续阅读开发者文档的其它章节来获取更多 TiDB 应用开发的最佳实践。例如：插入数据，更新数据，删除数据，单表读取，事务，SQL 性能优化等。
• 如果你更倾向于参与课程进行学习，我们也提供专业的 TiDB 开发者课程支持，并在考试后提供相应的资格认证。