planetscale-best-practices-matrix

ベストプラクティスのマトリックス

目的

データベースで見つかった事項を、推奨される PlanetScale の機能に対応付けます。評価で主要な安全性および運用面の項目を見落とさないようにするために使用してください。

エンジン共通の推奨事項

Query Insights

すべての本番データベースで、以下を推奨します。

• 遅いクエリ、高コストのクエリ、高頻度のクエリ、エラーが発生しているクエリのパターンを確認します。
• Postgres では、CPU の負荷を診断する際に、Insights API で sort=cpuTime を指定して Insights を CPU 順に並べ替えます。
• シャーディングされた Vitess では、クエリパターンごとの vindex の使用状況と、インデックスまたはルーティングの変更後の使用傾向を確認します。
• リグレッションとデプロイを関連付けます。
• タグやコメントを使って、クエリをコードに対応付けます。
• Query Insights でのタグの絞り込みとナビゲーションを使用します。両エンジンのタグ API（insights/tags、insights/tags/summaries）に加え、Vitess ダッシュボードでの tag:key:value による絞り込みと、実行ごとのタグ詳細表示を使用します。
• 異常をアラートや自動化の入力として使用します。

Webhooks

運用イベントについて、以下を推奨します。

• 異常。
• ストレージの逼迫。
• ブランチの準備完了／スリープ。
• プライマリへの昇格。
• メンテナンス。
• 利用可能な場合は、スキーマの推奨事項。
• Vitess のデプロイリクエストのライフサイクル。

MCP とエージェント

以下を推奨します。

• ほとんどの自律的な分析には、インサイト専用の MCP を使用します。
• フル MCP は、スコープを限定し、デフォルトで読み取り専用にする場合にのみ使用します。
• データベースの指定と安全性のルールを AGENTS.md に記述します。
• エージェントは PR／issue／変更計画を作成し、データベースの変更は人間が承認します。

SQLCommenter／クエリタグ

以下を推奨します。

• フレームワーク標準の、SQLCommenter 互換の計装を追加します。
• カーディナリティの低いタグを使用します。
• アプリケーション、サービス、ルート／ジョブ、機能、ソース、リリース SHA を含めます。
• PII や上限のない ID は避けます。

スキーマ推奨事項のワークフロー

以下を推奨します。

• 未対応の推奨事項をトリアージします。
• コードおよび Insights と関連付けます。
• マイグレーションまたはブランチの変更に反映します。
• 本番環境に適用する前にテストします。
• 承認済みのワークフローを通じてのみ適用します。

Vitess 固有の推奨事項

安全なマイグレーション

本番ブランチと、デプロイリクエストを受け付けるステージングブランチで推奨します。

デプロイリクエスト

保護されたブランチに対するスキーマ変更で推奨します。

強制切り替えの規律

長時間実行中のトランザクションによって遅延しているデプロイリクエストに対して、誰が「force cutover now」を使用できるかを文書化することを推奨します。これは実行中のトランザクションを停止してスキーマの切り替えを完了させるため、頻繁に使用する場合は、強制切り替えをデータベースのデフォルトとして有効にする前に、ワークロードを確認してください。

管理者による承認

複数の管理者がいる組織では、本番環境のデプロイリクエストで推奨します。

管理者が 1 人の組織では、承認だけではエージェントに対する防護策になりません。その管理者が同じデプロイリクエストを作成して承認できるためです。エージェントには別の ID を使用するか、デプロイリクエストを承認できないサービストークンを使用してください。

ゲート付きデプロイ

切り替えのタイミングと人間による制御が重要な場合に推奨します。

スキーマのリバート手順書

リバートの責任範囲と、アプリケーションのロールバックとの関係を文書化することを推奨します。

ブランチ戦略

保護されたターゲットで安全なマイグレーションを行う、本番、ステージング、短期間の開発用ブランチを推奨します。

シャーディング／キースペースの確認

クエリパターンや成長状況から、シャードを考慮できていない問題が示唆される場合に推奨します。自動で再シャーディングしないでください。

Postgres 固有の推奨事項

ユーザー定義ロール

アプリケーションサーバーでは、デフォルトのロールではなくユーザー定義ロールを推奨します。ロールを Terraform で管理し、パスワードを Terraform の state に含めたくない場合は、planetscale_postgres_redacted_branch_role と、別途用意したパスワードリセットおよびシークレットマネージャーへの保存経路を推奨します。

pg_strict

評価後、アプリケーションロールでの使用を推奨します。特に、誤ってテーブル全体を更新／削除してしまうミスを防ぐのに役立ちます。

Traffic Control

エージェント、エクスポート、レポート、ワーカー、インテグレーション、BI、既知の高コストなフィンガープリントのリソース分離に推奨します。

バックアップとPITR

保持期間とリストア訓練の実施状況を確認することを推奨します。 Terraform が顧客の信頼できる唯一の情報源である場合は、バックアップポリシーをそこで管理し、バックアップ体制の変更がインフラストラクチャコードとしてレビューされるよう推奨します。

PgBouncer とコネクションプーリング

コネクションの頻繁な切り替わりやサーバーレス／エッジの動作によって負荷が生じている場合は、トランザクションプーリングの制約を踏まえて推奨します。

プライベート接続とIP制限

プライベートネットワーク体制やパブリックへの露出低減を必要とする顧客に推奨します。変更は本番環境にリスクをもたらすものとして扱ってください。

拡張機能

ユースケースが明確で、再起動／有効化の影響が許容されている場合にのみ推奨します。 低速クエリの実行計画を自動的にログに記録することで診断が大幅に改善し、ログ量も許容できる場合は、auto_explain を含めてください。 Terraform で Postgres のブランチパラメーターまたはサポート対象の拡張機能を管理している場合は、その信頼できる唯一の情報源を承認済みのダッシュボード／API 変更に合わせてください。

ライブ接続

アクティブな接続圧迫インシデント中に pscale branch connections top を調査し、通常のデータベース接続容量に頼ることなく、セッション、ブロッカー、アイドル・イン・トランザクションの根本原因を特定することを推奨します。

出力

各マトリックス項目について、以下を記載してください。

• 該当状況：はい／いいえ／不明。
• 現在の状態。
• ギャップ。
• 価値：この機能が対応する具体的な測定結果（クエリフィンガープリント、異常件数、インシデント、メトリクス）。仕組みと測定結果を記載してください。ギャップとは、定量化された影響を伴う機能上の不足であり、安全に回避できたリスクではありません。
• 推奨ID。
• 承認要件。

最後に、以下を記載してください。

「変更は適用されていません。」