トラブルシューティング

Prisma Accelerateを使用する際、開発および運用中に特定のエラーコードによって強調表示されるエラーに遭遇することがよくあります。アプリケーションの円滑な運用を確保するためには、これらのエラーの意味、発生原因、および解決方法を理解することが重要です。このガイドは、Prisma Accelerateで遭遇する特定のエラーコードのトラブルシューティングを行うための洞察と手順を提供することを目的としています。

P6009 (ResponseSizeLimitExceeded)

このエラーは、データベースクエリからのレスポンスサイズが設定されたクエリレスポンスサイズ制限を超えた場合にトリガーされます。5MBを超えるデータの取得は、複数のネットワークレイヤーが原因でアプリケーションの速度を大幅に低下させる可能性があるため、アプリケーションのパフォーマンスを保護するためにこの制限を実装しました。通常、5MBを超えるデータの送信は、ETL（抽出、変換、ロード）操作を実行する場合によく見られます。ただし、トランザクショナルクエリ、ユーザーインターフェース用のリアルタイムデータフェッチ、バルクデータ更新、またはETLコンテキスト外の分析用の大規模データセットの集計などの他のシナリオでは、一般的に避ける必要があります。これらのユースケースは不可欠ですが、多くの場合、設定されたクエリレスポンスサイズ制限内で動作するように最適化でき、よりスムーズなパフォーマンスとより良いユーザーエクスペリエンスを保証できます。

P6009の考えられる原因

レスポンスでの画像/ファイルの送信

テーブル内に保存されている画像またはファイルがフェッチされると、レスポンスサイズが大きくなり、このエラーが発生する可能性があります。データベースにアセットを直接保存することは、データベースのパフォーマンスとスケーラビリティに大きな影響を与えるため、一般的に推奨されません。パフォーマンスに加えて、データベースのバックアップが遅くなり、ルーチンバックアップのストレージコストが大幅に増加します。

推奨される解決策： クエリレスポンスサイズ制限を大きく設定してください。制限をさらに超える場合は、画像またはファイルをCloudflare R2、AWS S3、またはCloudinaryのようなBLOBストアに保存することを検討してください。これらのサービスを使用すると、アセットを最適に保存し、アクセス用のURLを返すことができます。アセットをデータベースに直接保存する代わりに、URLを保存すると、レスポンスサイズが大幅に削減されます。

データの過剰フェッチ

特定の場合には、大量のレコードまたはフィールドが意図せずにフェッチされ、設定されたクエリレスポンスサイズ制限を超える結果になります。これは、クエリのwhere句が正しくないか、完全に欠落している場合に発生する可能性があります。

推奨される解決策： クエリレスポンスサイズ制限を大きく設定してください。制限をさらに超える場合は、where句が期待どおりにデータをフィルタリングしていることを再確認してください。レコードのフェッチが多すぎるのを防ぐために、ページネーションの使用を検討してください。さらに、select句を使用して、必要なフィールドのみを返し、レスポンスサイズを削減します。

大量のデータのフェッチ

多くのデータ処理ワークフロー、特にETL（抽出 - 変換 - ロード）プロセスやスケジュールされたCRONジョブを含むワークフローでは、分析、レポート作成、またはさらなる処理のために、データソース（データベース、API、ファイルシステムなど）から大量のデータを抽出する必要があります。分析処理のために大量のデータをフェッチするETL/CRONワークロードを実行している場合、この制限に達する可能性があります。

推奨される解決策： クエリレスポンスサイズ制限を大きく設定してください。制限を超える場合は、クエリをバッチに分割することを検討してください。このアプローチにより、各バッチはデータの一部のみをフェッチし、単一の操作でサイズ制限を超えるのを防ぎます。

P6004 (QueryTimeout)

このエラーは、データベースクエリが設定されたクエリタイムアウト制限内にレスポンスを返せない場合に発生します。クエリタイムアウト制限には、プールからの接続の待機時間、データベースへのネットワーク遅延、およびクエリ自体の実行時間が含まれます。システムリソースを過負荷にする可能性のある意図しない長時間実行クエリを防ぐために、この制限を適用しています。

Accelerateのクロスリージョンネットワークの時間は、設定されたクエリタイムアウト制限の制限から除外されます。

P6004の考えられる原因

このエラーは、多くの理由で発生する可能性があります。主な原因のいくつかは次のとおりです。

高トラフィックと接続不足

アプリケーションが非常に高いトラフィックを受信しており、データベースで使用可能な接続数が十分でない場合、クエリは接続が利用可能になるのを待つ必要があります。この状況は、クエリが接続のために設定されたクエリタイムアウト制限よりも長く待機し、この時間内にサービスを受けられない場合、最終的にタイムアウトエラーをトリガーする可能性があります。

推奨される解決策：プラットフォーム環境でAccelerateを設定する際に、接続文字列パラメータで指定されたconnection_limitを確認し、必要に応じて増やしてください（リファレンス）。この制限は、データベースの最大接続数と一致する必要があります。

デフォルトでは、データベース接続文字列で異なるconnection_limitが指定されていない限り、接続制限は10に設定されています。

長時間実行クエリ

クエリの応答が遅く、接続が利用可能な場合でも、設定されたクエリタイムアウト制限に達する可能性があります。これは、単一のクエリで非常に大量のデータがフェッチされている場合、またはテーブルから適切なインデックスが欠落している場合に発生する可能性があります。

推奨される解決策：クエリタイムアウト制限を大きく設定してください。制限を超える場合は、実行速度の遅いクエリを特定し、必要なデータのみをフェッチしてください。select句を使用して特定のフィールドを取得し、不要なデータのフェッチを避けてください。さらに、クエリ効率を向上させるために適切なインデックスを追加することを検討してください。トランザクショナルクエリへの影響を防ぐために、長時間実行クエリを別の環境に隔離することもできます。

データベースリソースの競合

一般的でありながら対処が難しい問題は、同じデータベースで動作する他のサービスが、大量の分析またはデータ処理タスクを実行し、データベースリソースを大幅に消費する場合です。これらの操作は、データベース接続と処理能力を独占する可能性があり、簡単なクエリでさえタイムリーに実行できないシナリオにつながります。この「ビジー」または「ノイジー」なデータベース環境は、通常は高速に実行されるクエリを遅くしたり、タイムアウトさせたりする可能性があります。特に、他のサービスからのアクティビティが多い期間に顕著です。

ユーザーは、データベースの負荷を測定するためにCPUとメモリの使用率メトリックに依存することがよくありますが、これは誤解を招く可能性があります。これらは重要な指標ですが、データベースの運用状態を完全に表しているとは限りません。読み取り、書き込み、および待機時間などの直接的なメトリックは、データベースのパフォーマンスをより明確に把握でき、綿密に監視する必要があります。これらのメトリックの顕著な低下は、特にクエリまたはデータモデルの変更がない場合に、外部からの圧力がデータベースのパフォーマンスに影響を与えていることを示唆しています。

推奨される解決策：通常は高速なクエリが断続的に遅くなったり、変更なしにタイムアウトしたりする場合は、競合するクエリが同じデータベーステーブルに圧力をかけている可能性があります。これを診断するには、監視ツールを採用するか、データベースに固有の機能を利用して、読み取り、書き込み、および待機時間を観察します。このような監視により、観察されたパフォーマンスの低下と一致するアクティビティパターンまたはスパイクが明らかになります。

さらに、重要なクエリを定期的に精査および改良し、テーブルに適切なインデックスが設定されていることを確認することが重要です。このプロアクティブなアプローチにより、これらのクエリが競合するワークロードによって引き起こされる速度低下の影響を受けにくくなります。

P6009およびP6004エラーに関する考慮事項

Prisma ORMをネイティブでサポートするランタイムの場合、2つのPrismaClientインスタンスを作成することを検討できます。1つはAccelerate接続文字列（prisma://プレフィックス付き）、もう1つは直接データベース接続文字列（postgres://、mysql://などプレフィックス付き）です。このアプローチの主なアイデアは、特定のクエリに対してAccelerateをバイパスすることです。

ただし、使用可能な接続は両方のPrismaClientインスタンス間で分割されることに注意してください。複数のインスタンスを管理することの意味、特に直接データベース接続に関して理解することが重要です。直接データベース接続文字列を持つPrismaClientインスタンスを利用するということは、この接続がデータベースと直接対話することを意味します。

直接接続とAccelerateによって管理される接続は、同じ基盤となるデータベース接続プールを共有するため、このアプローチには慎重な検討が必要です。これにより、リソースの競合が発生し、データベースサービスのパフォーマンスと可用性に影響を与える可能性があります。

さらに、直接接続はデータベースのパフォーマンスと可用性に大きな影響を与える可能性があります。大量のリソースを消費する操作は、同じデータベースに依存する他のユーザーまたはプロセスのサービスを低下させる可能性があります。

アプリケーションのランタイム環境がPrisma ORMをネイティブでサポートしており、P6009およびP6004エラーを回避するためにこの戦略を検討している場合は、2つのPrismaClientインスタンスを作成する可能性があります。

1. 一般的な操作には、Accelerate接続文字列（prisma://プレフィックス付き）を使用するインスタンス。
2. 特定の操作には、直接データベース接続文字列（例：postgres://、mysql://などプレフィックス付き）を使用する別のインスタンス。これは、設定されたクエリ制限タイムアウトを超えるか、設定されたクエリレスポンスサイズ制限よりも大きいレスポンスになることが予想される操作です。

export const prisma = new PrismaClient({
  datasourceUrl: process.env.DIRECT_DB_CONNECTION,
})

export const prismaAccelerate = new PrismaClient({
  datasourceUrl: process.env.ACCELERATE_CONNECTION,
}).$extends(withAccelerate())

この設定により、特定​​の操作を直接接続を介して戦略的に誘導し、前述のエラーが発生するリスクを軽減できます。ただし、この決定は、潜在的な結果を包括的に理解し、データベースインフラストラクチャが全体的なパフォーマンスと可用性を損なうことなくこの追加の負荷をサポートできるかどうかを評価した上で行う必要があります。

また、サービス中断中にAccelerateが直接接続文字列にフォールバックしないのはなぜですか？も参照してください。

P6008 (ConnectionError|EngineStartError)

このエラーは、Prisma Accelerateがデータベースへの接続を確立できないことを示しており、いくつかの理由が考えられます。

P6008の考えられる原因

データベースがパブリックにアクセス可能ではない

データベースがVPC内にある場合、またはアクセスが特定のIPアドレスに制限されている場合、Accelerateで静的IPが有効になっていない場合、または静的IPがデータベースファイアウォールで許可されていない場合に、このエラーが発生する可能性があります。

推奨される解決策： Accelerateの静的IPを有効にし、提供された静的IPアドレスからのアクセスを許可するようにデータベースファイアウォールを構成します。

データベースホスト/ポートに到達できない

データベースのサーバーアドレス（ホスト名）とポートが正しくないか、到達できない場合、このエラーが発生する可能性があります。

推奨される解決策： Prisma Accelerateプロジェクトの作成時に提供されたデータベース接続文字列のホスト名/ポートを確認してください。さらに、データベースGUIツール（例：Prisma Studio、TablePlus、またはDataGrip）を使用してデータベースに接続し、さらに調査してください。

ユーザー名/パスワード/データベース名が正しくない

このエラーは、Prisma Accelerateに誤った資格情報が提供され、データベースへの接続を確立できなくなる場合に発生する可能性があります。

推奨される解決策： Prisma Accelerateに提供された接続文字列で、データベースのユーザー名、パスワード、および名前が正しいことを確認してください。これらの資格情報がデータベースに必要な資格情報と一致していることを確認してください。直接データベースGUIツールを使用して接続をテストすることも、提供された資格情報が正しいかどうかを確認するのに役立ちます。

データベースの応答に時間がかかりすぎている

データベースが接続要求への応答に時間がかかりすぎている場合、Prisma Accelerateがタイムアウトし、このエラーをスローする可能性があります。これは、データベースがアクティブでない場合、またはスリープモードから復帰している場合に発生する可能性があります。

推奨される解決策： データベースがアクティブで到達可能であることを確認してください。データベースがスリープモードになっている場合は、直接データベースGUIツールを使用してリクエストを送信するか、データベースの管理コンソールを使用してウェイクアップしてみてください。

P5011 (TooManyRequests)

このエラーは、Prisma Accelerateが許容可能なしきい値を超える大量のリクエストを検出した場合に発生します。これは、Prisma Accelerateと基盤となるデータベースの両方を過剰な負荷から保護するための保護手段として機能します。

P5011の考えられる原因

アグレッシブなリトライループ

アプリケーションが、特に特定のエラーを受信した後、クエリを即座に、または最小限の遅延で再試行する場合、リクエストの急速な蓄積がしきい値を超える可能性があります。

推奨される解決策

• 指数バックオフ戦略を実装します。即座に、または固定遅延で再試行するのではなく、失敗するたびに遅延期間を徐々に増やします。
• これにより、システムが回復する時間を確保し、Prisma Accelerateとデータベースに過負荷がかかる可能性を減らすことができます。

突然のトラフィックスパイク

予測不可能なトラフィックの急増（たとえば、製品の発売、フラッシュセール、またはバイラル成長イベント中）は、しきい値が満たされ、P5011が発生する可能性があります。

推奨される解決策

• Prisma Accelerateとデータベースの両方に対して、プロアクティブなスケーリング戦略を検討してください。
• トラフィックとリソースの使用状況を監視します。急増が予想される場合は、キャパシティプランニングと構成の調整の可能性についてサポートにお問い合わせください。

長期または計画的な高ワークロード

バルクデータインポート、ETL操作、または拡張CRONジョブなどの特定のプロセスは、時間の経過とともに継続的な高クエリ量を生成する可能性があります。

推奨される解決策

• バッチ処理またはチャンク処理の手法を使用して、大きな操作を小さなパーツに分割します。
• 負荷をより均等に分散するために、スロットリングまたはスケジューリングを確立します。

その他のエラー

MySQL（Aiven）のエラー：「リクエストを処理できませんでした。更新してもう一度お試しください。」

問題

?ssl-mode=REQUIREDパラメータを含むAiven MySQL接続文字列を使用すると、次のエラーが発生する可能性があります。

We were unable to process your request. Please refresh and try again.

原因

ssl-mode=REQUIREDパラメータはAccelerateと互換性がないため、接続の問題が発生します。

推奨される解決策

このエラーを解決するには、MySQL接続文字列から?ssl-mode=REQUIREDパラメータを削除します。

例

• 元の接続文字列：mysql://username:password@host:port/database?ssl-mode=REQUIRED
• 更新された接続文字列：mysql://username:password@host:port/database