Prisma Accelerate入門

前提条件

Accelerateを始めるには、以下が必要です。

• A
• Prisma Client 4.16.1以上を使用するプロジェクト。インタラクティブトランザクションを使用しているプロジェクトの場合は、5.1.1以上を使用する必要があります。（常にPrismaの最新バージョンを使用することをお勧めします。）
• ホストされたPostgreSQL、MySQL/MariaDB、PlanetScale、CockroachDB、またはMongoDBデータベース

1. Accelerateを有効にする

Prisma Data Platformプロジェクトに移動し、環境を選択し、データベース接続文字列を提供し、データベースに最も近いリージョンを選択して、Accelerateを有効にします。

注

信頼できるIPアドレスによるIP許可リストまたはファイアウォール構成が必要な場合は、セキュリティを強化するために静的IPを有効にしてください。Platform ConsoleでAccelerateの静的IPを有効にする方法の詳細はこちらをご覧ください。

2. アプリケーションにAccelerateを追加する

2.1. データベース接続文字列を更新する

有効にすると、リクエストを認証するために新しいAccelerate接続文字列で使用するAPIキーを生成するように求められます。

直接データベースURLを新しいAccelerate接続文字列に置き換えます。

.env

# New Accelerate connection string with generated API_KEY
DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=__API_KEY__"

# Previous (direct) database connection string
# DATABASE_URL="postgresql://user:password@host:port/db_name?schema=public"

更新された接続文字列は、Prismaスキーマファイルのデータソースurlとして使用されます。

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

Prisma MigrateとIntrospectionはprisma://接続文字列では機能しません。これらの機能を引き続き使用するには、DIRECT_DATABASE_URLという名前の新しい変数を.envファイルに追加し、その値に直接データベース接続文字列を設定してください。

.env

DATABASE_URL="prisma://accelerate.prisma-data.net/?api_key=__API_KEY__"
DIRECT_DATABASE_URL="postgresql://user:password@host:port/db_name?schema=public"

次に、Prismaスキーマのdatasourceブロックに、directUrlという名前のフィールドを次のように追加します。

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_DATABASE_URL")
}

この構成が提供されている場合、マイグレーションとイントロスペクションは、urlで定義された接続文字列ではなく、directUrl接続文字列を使用します。

directUrlは、マイグレーションとイントロスペクションを実行するのに役立ちます。ただし、アプリケーションでAccelerateを使用するためにdirectUrlは必要ありません。

注

PostgreSQLでPrismaを使用している場合、Prisma MigrateとIntrospectionはprisma+postgres://接続文字列で機能するため、directUrlは必要ありません。

2.2. Accelerate Prisma Client拡張機能をインストールする

情報

💡 Accelerateには、Prisma Clientバージョン4.16.1以上および@prisma/extension-accelerateバージョン1.0.0以上が必要です

Prisma ClientとAccelerate Prisma Client拡張機能の最新バージョンをインストールします

npm install @prisma/client@latest @prisma/extension-accelerate

2.3. Accelerate用のPrisma Clientを生成する

Prismaバージョン5.2.0以降を使用している場合、Prisma Clientはデータベース接続文字列のプロトコルに応じてデータベースへの接続方法を自動的に決定します。DATABASE_URLの接続文字列がprisma://で始まる場合、Prisma ClientはPrisma Accelerateを使用してデータベースに接続しようとします。

AWS EC2にデプロイされたサーバーなど、長時間実行されるアプリケーションサーバーでPrisma Accelerateを使用する場合、次のコマンドを実行してPrisma Clientを生成できます

npx prisma generate

サーバーレスまたはエッジアプリケーションでPrisma Accelerateを使用する場合、次のコマンドを実行してPrisma Clientを生成することをお勧めします

npx prisma generate --no-engine

--no-engineフラグは、生成されたPrisma ClientにQuery Engineファイルが含まれるのを防ぎ、アプリケーションのバンドルサイズを小さく保ちます。

警告

Prismaバージョンが5.2.0より低い場合は、--accelerateオプションを指定してPrisma Clientを生成します

npx prisma generate --accelerate

Prismaバージョンが5.0.0より低い場合は、--data-proxyオプションを指定してPrisma Clientを生成します

npx prisma generate --data-proxy

2.4. Accelerate拡張機能でPrisma Clientインスタンスを拡張する

既存のPrisma ClientインスタンスをAccelerate拡張機能で拡張するには、以下を追加します

import { PrismaClient } from '@prisma/client'
import { withAccelerate } from '@prisma/extension-accelerate'

const prisma = new PrismaClient().$extends(withAccelerate())

エッジランタイム（Cloudflare Workers、Vercel Edge Functions、Deno Deploy、Supabase Edge Functionsなど）にデプロイする場合は、代わりにエッジクライアントを使用してください

import { PrismaClient } from '@prisma/client/edge'
import { withAccelerate } from '@prisma/extension-accelerate'

const prisma = new PrismaClient().$extends(withAccelerate())

VS Codeが$extendsメソッドを認識しない場合は、問題の解決方法についてこのセクションを参照してください。

Accelerate拡張機能を他の拡張機能またはミドルウェアと共に使用する

拡張機能は次々と適用されるため、正しい順序で適用してください。拡張機能は動作を共有できず、最後に適用された拡張機能が優先されます。

アプリケーションでPrisma Optimizeを使用している場合は、Accelerate拡張機能の前に適用してください。例：

const prisma = new PrismaClient().$extends(withOptimize()).$extends(withAccelerate())

アプリケーションでPrisma Middlewareを使用している場合は、Prisma Client拡張機能（Accelerateなど）の前に追加されていることを確認してください。例：

const prisma = new PrismaClient().$use(middleware).$extends(withAccelerate())

2.5. データベースクエリでAccelerateを使用する

withAccelerate拡張機能は主に2つのことを行います

• クエリごとにキャッシュ戦略を定義できる、適用可能な各モデルメソッド内のcacheStrategyフィールドへのアクセスを提供します。
• すべてのクエリをコネクションプーラー経由でルーティングします。

キャッシュ戦略なしでコネクションプールのみを使用する

キャッシュ戦略を適用せずに、Accelerateのコネクションプーリング機能を活用したい場合は、Accelerateなしの場合と同じようにクエリを実行できます。

Accelerateを有効にし、Accelerate接続文字列を提供することで、クエリはデフォルトでコネクションプーラーを使用するようになります。

キャッシュ戦略を定義する

特定のクエリのキャッシュ戦略を定義できる新しいcacheStrategyプロパティでクエリを更新します

const user = await prisma.user.findMany({
  where: {
    email: {
      contains: 'alice@prisma.io',
    },
  },
  cacheStrategy: { swr: 60, ttl: 60 },
})

上記の例では、swr: 60およびttl: 60は、Accelerateが60秒間キャッシュされたデータを提供し、その後Accelerateがバックグラウンドで新しいデータを取得している間、さらに60秒間提供することを意味します。

これで、キャッシュされたクエリのパフォーマンスが向上していることがわかるはずです。

情報

アプリケーションに最適な戦略に関する情報については、キャッシュ戦略の選択を参照してください。

情報

Prismaバージョン5.2.0以降では、Accelerate接続文字列でPrisma Studioを使用できます。

キャッシュを無効化して、キャッシュされたクエリ結果を最新の状態に保つ

アプリケーションがリアルタイムまたはニアリアルタイムデータを必要とする場合、キャッシュの無効化により、大きなttl（Time-To-Live）またはswr（Stale-While-Revalidate）キャッシュ戦略を使用している場合でも、ユーザーが最新のデータを確認できるようになります。キャッシュを無効にすることで、拡張されたキャッシュ期間をバイパスして、必要なときにいつでもライブデータを表示できます。

たとえば、ダッシュボードに顧客情報が表示され、顧客の連絡先の詳細が変更された場合、キャッシュの無効化により、そのデータのみを即座に更新でき、サポートスタッフはキャッシュの有効期限が切れるのを待つことなく常に最新の情報を確認できます。

キャッシュされたクエリ結果を無効にするには、タグを追加してから、$accelerate.invalidate APIを使用できます。

注

オンデマンドキャッシュの無効化は、有料プランで利用できます。詳細については、料金をご覧ください。

以下のクエリを無効にするには

await prisma.user.findMany({
  where: {
    email: {
      contains: "alice@prisma.io",
    },
  },
  cacheStrategy: {
    swr: 60,
    ttl: 60,
    tags: ["emails_with_alice"],
  },
});

$accelerate.invalidate APIにキャッシュタグを提供する必要があります

try {
  await prisma.$accelerate.invalidate({
    tags: ["emails_with_alice"],
  });
} catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError) {
    // The .code property can be accessed in a type-safe manner
    if (e.code === "P6003") {
      console.log(
        "You've reached the cache invalidation rate limit. Please try again shortly."
      );
    }
  }
  throw e;
}