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

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

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

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

注記：

このチュートリアルは、TiDB サーバーレス、TiDB 専用、および TiDB セルフホストで動作します。

前提条件

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

• Node.js >= 16.x がマシンにインストールされている。
• ギットマシンにインストールされています。
• TiDB クラスターが実行中です。

TiDB クラスターがない場合は、次のように作成できます。

• (推奨) TiDB サーバーレスクラスターの作成に従って、独自の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 Self-Hosted

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

次のコマンドを実行してプリズママイグレーションを呼び出し、 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 データベースにアクセスする場合もプリズマクライアントを生成します。

ステップ 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: 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レコードを作成し、TiDB によって生成されたidフィールドを含む、作成されたPlayerオブジェクトを返します。

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

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

クエリデータ

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

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

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

データを更新する

次のクエリは、ID 101のPlayerに50コインと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 リレーション モードの比較

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

• 外部キーは、TiDB v6.6.0 以降でサポートされる実験的機能であり、関連データのクロステーブル参照と、データの一貫性を維持するための外部キー制約が可能になります。

  警告

  外部キーは、小規模および中規模のデータ シナリオに適しています。大量のデータで外部キーを使用すると、パフォーマンスに重大な問題が発生し、システムに予期せぬ影響を与える可能性があります。外部キーを使用する予定がある場合は、最初に徹底的な検証を実行し、慎重に使用してください。

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

次のステップ

• ORM フレームワーク Prisma ドライバーの詳しい使用方法をPrisma のドキュメントから学びます。
• 開発者ガイドの章 ( データの挿入など) で TiDB 取引 SQLパフォーマンスの最適化 データを更新するベスト プラクティスクエリデータ学習データの削除ます。
• プロフェッショナルとしてTiDB 開発者コースを学び、試験合格後にTiDB 認定獲得します。

助けが必要？

不和またはサポートチケットを作成するについて質問してください。