TiDB CloudサーバーレスDriverPrisma チュートリアル

プリズマはオープンソースの次世代 ORM（オブジェクトリレーショナルマッピング）であり、開発者がデータベースを直感的、効率的、かつ安全に操作できるようにします。TiDB TiDB Cloud は@tidbcloud/プリズマアダプター提供し、 TiDB Cloudサーバーレスドライバーで HTTPS 経由でプリズマクライアント使用できます。従来の TCP 方式と比較して、 @tidbcloud/プリズマアダプターは以下の利点があります。

サーバーレス環境での Prisma クライアントのパフォーマンスが向上
エッジ環境で Prisma Client を使用する機能

このチュートリアルでは、サーバーレス環境とエッジ環境で@tidbcloud/プリズマアダプター使用する方法について説明します。

インストール

@tidbcloud/プリズマアダプターとTiDB Cloudサーバーレスドライバー両方をインストールする必要があります。5 またはお好みのパッケージマネージャーを使用しnpmインストールできます。

npm を例にとると、インストールには次のコマンドを実行できます。

npm install @tidbcloud/prisma-adapter
npm install @tidbcloud/serverless

`driverAdapters`を有効にする

Prismaアダプタを使用するには、 schema.prismaファイルのdriverAdapters機能を有効にする必要があります。例：

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider     = "mysql"
  url          = env("DATABASE_URL")
}

Prismaクライアントを初期化する

Prisma Client を使用する前に、 @tidbcloud/prisma-adapterで初期化する必要があります。

v6.6.0 より前のバージョン@tidbcloud/prisma-adapter場合:

import { connect } from '@tidbcloud/serverless';
import { PrismaTiDBCloud } from '@tidbcloud/prisma-adapter';
import { PrismaClient } from '@prisma/client';

// Initialize Prisma Client
const connection = connect({ url: ${DATABASE_URL} });
const adapter = new PrismaTiDBCloud(connection);
const prisma = new PrismaClient({ adapter });

@tidbcloud/prisma-adapter v6.6.0 以降のバージョンの場合:

import { PrismaTiDBCloud } from '@tidbcloud/prisma-adapter';
import { PrismaClient } from '@prisma/client';

// Initialize Prisma Client
const adapter = new PrismaTiDBCloud({ url: ${DATABASE_URL} });
const prisma = new PrismaClient({ adapter });

その後、Prisma Client からのクエリをTiDB Cloudサーバーレスドライバーに送信して処理することができます。

Node.js環境でPrismaアダプターを使用する

このセクションでは、Node.js 環境で@tidbcloud/prisma-adapter使用する方法の例を示します。

始める前に

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

Node.js >= 18.0.0。
npmまたはお好みのパッケージマネージャーを使用します。
TiDB Cloud Serverless クラスター。お持ちでない場合は、 TiDB Cloud Serverless クラスターを作成するご利用ください。

ステップ1. プロジェクトを作成する

prisma-exampleという名前のプロジェクトを作成します。
```
mkdir prisma-example
cd prisma-example
```
@tidbcloud/prisma-adapterドライバーアダプター、 @tidbcloud/serverlessサーバーレスドライバー、および Prisma CLI をインストールします。
以下のコマンドはパッケージマネージャーとしてnpmを使用します。1 npm install @tidbcloud/serverless実行すると、プロジェクトディレクトリにnode_modulesディレクトリとpackage.jsonファイルが作成されます。
```
npm install @tidbcloud/prisma-adapter
npm install @tidbcloud/serverless
npm install prisma --save-dev
```

package.jsonファイルで、 type: "module"を追加して ES モジュールを指定します。

{
  "type": "module",
  "dependencies": {
    "@prisma/client": "^6.6.0",
    "@tidbcloud/prisma-adapter": "^6.6.0",
    "@tidbcloud/serverless": "^0.1.0"
  },
  "devDependencies": {
    "prisma": "^6.6.0"
  }
}

ステップ2. 環境を設定する

TiDB Cloud Serverlessクラスターの概要ページで、右上隅の「接続」をクリックし、表示されるダイアログからデータベースの接続文字列を取得します。接続文字列は以下のようになります。
```
mysql://[username]:[password]@[host]:4000/[database]?sslaccept=strict
```
プロジェクトのルートディレクトリに.envという名前のファイルを作成し、次のようにDATABASE_URL名前の環境変数を定義して、この変数内のプレースホルダー[]接続文字列内の対応するパラメーターに置き換えます。
```
DATABASE_URL='mysql://[username]:[password]@[host]:4000/[database]?sslaccept=strict'
```
注記：
@tidbcloud/prisma-adapter HTTPS 経由の Prisma Client の使用のみをサポートします。2 とプリズママイグレーションプリズマイントロスペクション、従来の TCP 接続が引き続き使用されます。Prisma Client のみを使用する必要がある場合は、 DATABASE_URL mysql://[username]:[password]@[host]/[database]形式に簡略化できます。
.envファイルから環境変数を読み込むにはdotenvインストールします。
```
npm install dotenv
```

ステップ3. スキーマを定義する

schema.prismaという名前のファイルを作成します。このファイルには、 driverAdaptersプレビュー機能を組み込み、 DATABASE_URL環境変数を参照します。以下にファイルの例を示します。
```
// schema.prisma
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider     = "mysql"
  url          = env("DATABASE_URL")
} 
```

schema.prismaファイルで、データベーステーブルのデータモデルを定義します。次の例では、 user名前のデータモデルが定義されています。

// schema.prisma
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider     = "mysql"
  url          = env("DATABASE_URL")
} 

// define a data model according to your database table
model user {
  id    Int     @id @default(autoincrement())
  email String? @unique(map: "uniq_email") @db.VarChar(255)
  name  String? @db.VarChar(255)
}

データベースをPrismaスキーマと同期します。TiDB TiDB Cloud Serverlessクラスターにデータベーステーブルを手動で作成するか、Prisma CLIを使用して以下の手順で自動的に作成することもできます。
```
npx prisma db push
```
このコマンドは、 @tidbcloud/prisma-adapter使用したHTTPS接続ではなく、従来のTCP接続を介してTiDB Cloud Serverlessクラスターにテーブルuserを作成します。これは、Prisma Migrateと同じエンジンを使用しているためです。このコマンドの詳細については、スキーマのプロトタイプを作成する参照してください。
Prisma クライアントを生成します:
```
npx prisma generate
```
このコマンドは、Prisma スキーマに基づいて Prisma クライアントを生成します。

ステップ4. CRUD操作を実行する

hello-word.jsという名前のファイルを作成し、次のコードを追加して Prisma Client を初期化します。

import { PrismaTiDBCloud } from '@tidbcloud/prisma-adapter';
import { PrismaClient } from '@prisma/client';
import dotenv from 'dotenv';

// setup
dotenv.config();
const connectionString = `${process.env.DATABASE_URL}`;

// Initialize Prisma Client
const adapter = new PrismaTiDBCloud({ url: connectionString });
const prisma = new PrismaClient({ adapter });

Prisma ClientでCRUD操作を実行します。例:

// Insert
const user = await prisma.user.create({
  data: {
    email: 'test@pingcap.com',
    name: 'test',
  },
})
console.log(user)

// Query
console.log(await prisma.user.findMany())

// Delete
await prisma.user.delete({
   where: {
      id: user.id,
   },
})

Prisma Clientでいくつかのトランザクション操作を実行します。例:

const createUser1 = prisma.user.create({
  data: {
    email: 'test1@pingcap.com',
    name: 'test1',
  },
})
const createUser2 = prisma.user.create({
  data: {
    email: 'test1@pingcap.com',
    name: 'test1',
  },
})
const createUser3 = prisma.user.create({
  data: {
    email: 'test2@pingcap.com',
    name: 'test2',
  },
})

try {
  await prisma.$transaction([createUser1, createUser2]) // Operations fail because the email address is duplicated
} catch (e) {
  console.log(e)
}

try {
  await prisma.$transaction([createUser2, createUser3]) // Operations success because the email address is unique
} catch (e) {
  console.log(e)
}

エッジ環境でPrismaアダプターを使用する

Vercel Edge FunctionsやCloudflare Workersなどのエッジ環境では、 @tidbcloud/prisma-adapter v5.11.0以降のバージョンをご利用いただけます。