Prismaを使用してTiDBに接続する

TiDB は MySQL 互換データベースであり、PrismaNode.js 用の人気のあるオープンソース ORM フレームワークです。

このチュートリアルでは、TiDBとPrismaを使用して以下のタスクを実行する方法を学ぶことができます。

• 環境をセットアップしてください。
• Prismaを使用してTiDBに接続します。
• アプリケーションをビルドして実行します。オプションで、基本的な CRUD 操作用のサンプルコードスニペットを見つけることができます。

前提条件

このチュートリアルを完了するには、以下が必要です。

• お使いのコンピューターにNode.js >= 16.xがインストールされていること。
• お使いのマシンにGitがインストールされています。
• TiDBクラスタが稼働中です。

TiDBクラスタをお持ちでない場合は、以下の手順で作成できます。

• (推奨) TiDB Cloud Starterインスタンスを作成する。
• ローカルテスト用のTiDB Self-Managedクラスタをデプロイまたは本番のTiDB Self-Managedクラスタをデプロイ

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に接続してください。

ステップ4．データベーススキーマを初期化する

次のコマンドを実行してPrisma Migrateを呼び出し、 prisma/prisma.schemaで定義されたデータモデルでデータベースを初期化します。

npx prisma migrate dev

prisma.schemaで定義されたデータモデル：

// Define a Player model, which represents the `players` table.
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")
}

// Define a Profile model, which represents the `profiles` table.
model Profile {
  playerId  Int    @id @map("player_id")
  biography String @db.Text

  // Define a 1:1 relation between the `Player` and `Profile` models with foreign key.
  player    Player @relation(fields: [playerId], references: [id], onDelete: Cascade, map: "fk_profile_on_player_id")

  @@map("profiles")
}

Prisma でデータモデルを定義する方法については、データモデルデータモデルドキュメントを確認してください。

期待される実行出力:

Your database is now in sync with your schema.

✔ Generated Prisma Client (5.1.1 | library) to ./node_modules/@prisma/client in 54ms

このコマンドはprisma/prisma.schemaに基づいて TiDB データベースにアクセスするためのPrisma Clientも生成します。

ステップ5：コードを実行する

サンプルコードを実行するには、以下のコマンドを実行してください。

npm start

サンプルコードの主なロジック：

// Step 1. Import the auto-generated `@prisma/client` package.
import {Player, PrismaClient} from '@prisma/client';

async function main(): Promise<void> {
  // Step 2. Create a new `PrismaClient` instance.
  const prisma = new PrismaClient();
  try {

    // Step 3. Perform some CRUD operations with Prisma Client ...

  } finally {
    // Step 4. Disconnect Prisma Client.
    await prisma.$disconnect();
  }
}

void main();

期待される実行出力:

接続が成功すると、ターミナルには次のようにTiDBのバージョンが出力されます。

🔌 Connected to TiDB cluster! (TiDB version: 8.0.11-TiDB-v8.5.4)
🆕 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レコードを作成し、TiDB によって生成されたPlayerフィールドを含む、作成されたidオブジェクトを返します。

const player: Player = await prisma.player.create({
   data: {
      name: 'Alice',
      coins: 100,
      goods: 200,
      createdAt: new Date(),
   }
});

詳細については、データを挿入するを参照してください。

クエリデータ

次のクエリは、単一のPlayerオブジェクトを返します。このオブジェクトは、レコードが見つからない場合は、ID 101またはnullとなります。

const player: Player | null = prisma.player.findUnique({
   where: {
      id: 101,
   }
});

詳細については、 クエリデータを参照してください。

データの更新

以下のクエリは、 50の ID を持つ50にPlayerコインと101の商品を追加します。

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リレーションモードの比較

参照整合性をチェックするには、外部キー制約または Prisma リレーション モードを使用できます。

• 外部キー、TiDB v6.6.0 以降でサポートされている機能であり、v8.5.0 以降で一般的に利用可能です。外部キーを使用すると、関連データのテーブル間参照が可能になり、外部キー制約によって関連データの一貫性が確保されます。

  警告

  外部キーは、小規模から中規模のデータ量を扱う場合に適しています。大規模なデータ量で外部キーを使用すると、深刻なパフォーマンス問題が発生したり、システムに予期せぬ影響を及ぼしたりする可能性があります。外部キーを使用する場合は、事前に徹底的な検証を行い、慎重に使用してください。

• Prisma Relation ModePrisma Client側の参照整合性のエミュレーションです。ただし、参照整合性を維持するために追加のデータベース クエリが必要になるため、パフォーマンスに影響があることに注意してください。

次のステップ

• ORM フレームワーク Prisma ドライバーの使用方法の詳細についてはPrismaのドキュメントを参照してください。
• 開発者ガイドのデータを挿入する、データの更新、データを削除する、クエリデータ、トランザクション、SQLパフォーマンス最適化などの章を読んで、TiDB アプリケーション開発のベストプラクティスを学びましょう。
• プロフェッショナルなTiDB開発者向けコースコースを通じて学習し、試験に合格するとTiDB認定資格を取得します。

お困りですか？

• Discordor Slackコミュニティに質問してください。
• TiDB Cloudのサポートチケットを送信してください
• TiDB Self-Managedのサポートチケットを送信してください