メインコンテンツにスキップ

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スキーマファイルのdatasource urlとして使用されます。

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

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

.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は必要ありません。

注意

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

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

情報

💡 Accelerateには、Prisma Clientバージョン4.16.1以降と、@prisma/extension-accelerateバージョン1.0.0以降が必要です。

💡 Accelerate拡張機能@prisma/extension-accelerateバージョン2.0.0以降には、Node.jsバージョン18以降が必要です。

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

ServerlessまたはEdgeアプリケーションで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拡張機能を使用する​

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

アプリケーションで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;
}
© . All rights reserved.