planetscale-readonly-inventory

読み取り専用インベントリ

目的

変更を加えずに、PlanetScale データベースの根拠に基づいたインベントリを作成します。

許可される操作

デフォルトで許可される操作：

• 組織、データベース、ブランチ、キースペース、リージョン、サイズを一覧表示します。
• ブランチのメタデータを読み取ります。
• Webhook の設定を読み取ります。
• スキーマに関する推奨事項を読み取ります。
• MCP または API を通じて、Query Insights、異常、クエリパターンを読み取ります。
• トラフィック予算とルールを読み取ります。
• Postgres のロールと、機密情報を含まないロールのメタデータを読み取ります。
• バックアップスケジュールと復元のメタデータを読み取ります。
• ブランチのスキーマを読み取ります。
• Connections CLI ビューで、稼働中の接続／セッションのメタデータを調査します。
• リポジトリのファイルを調査して、フレームワーク、ORM、マイグレーション、SQL タギング、接続設定を確認します。
• Terraform またはその他の Infrastructure as Code 定義を調査して、PlanetScale のロール、バックアップ、バックアップポリシー、Postgres のパラメーター、サポート対象の拡張機能を確認します。

明示的な承認なしでは許可されない操作：

• 作成、更新、削除、有効化、無効化、リセット、デプロイ、復元、昇格、適用、または強制適用を行う操作。
• SQL による変更。
• オペレーターが認証情報に関する作業を明示的に依頼していない場合に、新しい認証情報を出力するコマンド。

インターフェースとドキュメントに基づく確認

推測せず、すべてのコマンドとエンドポイントを公式ドキュメントに照らして確認してください。PlanetScale では、エージェントが読み取れるドキュメントを公開しています。

• ドキュメントの目次：https://planetscale.com/docs/llms.txt
• 任意のドキュメントページを Markdown 形式で取得するには、URL の末尾に .md を追加します
• API リファレンス：https://planetscale.com/docs/openapi.yaml（OpenAPI 3.0）

エンドポイントを呼び出す前に、API リファレンスでパスを確認してください。未確認のパスからの 404 は、パスが間違っていることを示すものであり、調査結果ではありません。プラットフォームの状態として記録したり、それを根拠に「未設定」と結論付けたりしないでください。

確認済みのインターフェースに関する注意事項（コマンドが失敗した場合は、ドキュメントを再確認してください）：

• pscale database show <database> --org <org> — org は位置引数ではなく、フラグです。
• pscale api <path> は、organizations/{org}/databases/{db}/branches/{branch} のような org 相対パスを受け取ります。get サブコマンドや /v1/ プレフィックスはありません。クエリパラメーターは -Q key=value フラグで渡してください。パスに ? や & を埋め込むと、シェルのグロブ展開で問題が発生します。
• pscale webhook list <database> --org <org> — database は位置引数です。pscale backup list <database> <branch> には branch が必要です。
• pscale branch connections top <database> <branch> — 予約済みの管理接続を介して、Postgres と Vitess の両方で、稼働中の読み取り専用セッション一覧を取得できます。オペレーターがその操作を明示的に承認しない限り、クエリのキャンセルや接続の終了は行わないでください。
• Query Insights は公開 API です。稼働中のクエリテレメトリー： .../branches/{branch}/insights（パターンごとの統計情報。from／to／period、q、sort、dir、tablet_type、type、fields、ページネーションに対応）。同じブランチパス配下の関連エンドポイント： insights/errors、insights/anomalies、insights/tags、insights/tags/summaries、insights/{fingerprint}（個別の実行）、insights/{fingerprint}/summary、insights/{fingerprint}/traffic/budgets。query-patterns パスが返すのは、稼働中のパターンではなく、生成済みレポートのメタデータです。
• トラフィック予算：.../branches/{branch}/traffic/budgets。CLI に pscale traffic-control budget list はありません。在庫の確認には API を使用してください。
• Postgres のロール：.../branches/{branch}/roles で一覧を取得します。単一のロールは名前ではなく ID で取得します（pscale role get <db> <branch> <role-id>）。
• IP 制限：データベースレベルの organizations/{org}/databases/{db}/cidrs。ブランチレベルの IP 制限パスは有効ではありません。
• スキーマの推奨事項：データベースレベルの .../databases/{db}/schema-recommendations（ブランチレベルのパスは有効ではありません）。現在、レスポンスに next_page が含まれていても、page=2 をリクエストすると 404 が返されます。データベースオブジェクトの open_schema_recommendations_count を正確な合計数として使用し、返されたページはサンプルとして扱ってください。項目別リストが合計数の一部しか網羅していない場合は、レポートにその旨を記載してください。
• PITR の状態とブランチレベルのバックアップポリシーには、確認済みの読み取りパスがありません。バックアップの状況は pscale backup list とデータベースレベルのバックアップポリシーに基づいて記録し、PITR はパスを試さず「この実行では未評価」と記載してください。
• リストエンドポイントにはページネーションがあります。前述のスキーマ推奨事項のケースを除き、件数を報告する前に、すべてのページを取得し終えるまでページネーションパラメーターを使用してください。

アクセスエラー（403、トークンのスコープ不足、タイムアウト）は、オペレーター向けの内部実行ログに記録してください。これらは調査結果ではなく、顧客向けレポートには含めません（../planetscale-customer-report-template/SKILL.md を参照）。

インベントリのチェックリスト

データベースの識別情報

以下を記録します。

• 組織。
• データベース。
• ブランチ。
• エンジン：Vitess または Postgres。
• リージョンとクラウドプロバイダー。
• 本番／開発ブランチの状態。
• ブランチ保護と安全なワークフローの状態。
• サイズとクラスター構成。

ブランチとスキーマのワークフロー

Vitess について、以下を記録します。

• 本番ブランチ。
• 本番ブランチとステージングブランチで安全なマイグレーションが有効かどうか。
• オープン中のデプロイリクエスト。
• デプロイリクエストの承認設定。
• 保留中のスキーマ変更。
• ブランチ戦略に、安全なマイグレーションが有効なステージングブランチがあるかどうか。

Postgres について、以下を記録します。

• ブランチ一覧。
• ブランチがバックアップから作成されたか、空の状態から作成されたか。
• スキーマ変更が手動、マイグレーション、ORM のいずれで管理されているか。
• マイグレーションのテストに別のブランチを使用しているかどうか。
• チームが Vitess 形式のデプロイリクエストを想定しているかどうか。該当する場合は、Postgres のブランチでは同じ方法でデプロイリクエストを使用しないことを明記します。

オブザーバビリティ

以下を記録します。

• Insights を利用できるかどうか。
• クエリタグがあるかどうか。
• 表示されるタグ。
• カーディナリティの高いタグがあるかどうか。
• 完全なクエリ／生クエリの収集が有効かどうか。
• アクティブな異常。
• レイテンシー、読み取り行数、エラー率、実行回数のいずれかが高いクエリパターン。
• 使用中の Insights インターフェースで確認できる場合は、Postgres の CPU 負荷が高いクエリパターンと Vitess の vindex 使用データ。
• アプリケーションのデプロイ識別子がコメントまたはタグに表示されるかどうか。

推奨事項

以下を記録します。

• 未対応のスキーマに関する推奨事項。
• 推奨事項の種類。
• 影響を受けるテーブル／クエリ。
• 提案されている DDL またはアクション。
• 安全に評価するためのブランチ／デプロイのワークフローがあるかどうか。
• 推奨事項をアプリケーションコード、ORM マイグレーション、データベース DDL のいずれで実装できるか。

Webhook と自動化

以下を記録します。

• 設定済みの Webhook。
• 購読しているイベント。
• 有効状態。
• 最後の配信の成功または失敗。
• 配信先のカテゴリ：Slack、PagerDuty、内部自動化、CI、エージェントキュー、不明。
• Webhook の署名検証が文書化または実装されているかどうか。
• Webhook の処理が冪等かつ非同期かどうか。

Postgres Traffic Control

Postgres のみについて、以下を記録します。

• 既存の予算とルール。
• 予算のモード：オフ、警告、強制。
• 制限：レート、容量、バースト、同時実行数、警告しきい値。
• フィンガープリント、キースペース、クエリ種別、タグごとのルール。
• ルールが意味のある SQLCommenter タグに紐付けられているかどうか。
• 本番の予算が強制モードになっているかどうか。

Postgres の安全性

Postgres のみについて、以下を記録します。

• アプリケーションロールの使用状況。
• アプリケーションがデフォルトのロールを使用しているかどうか。
• アプリケーションロールが最小権限になっているかどうか。
• アプリケーションロールで pg_strict が有効かどうか。
• 適切なワークロードで PgBouncer を使用しているかどうか。
• インシデント発生中に、ライブ接続でブロッカー、トランザクション中のアイドル状態のセッション、接続の飽和が見られるかどうか。
• プライベート接続と IP 制限が設定されているかどうか。
• バックアップの保持期間と PITR が顧客の復旧要件を満たしているかどうか。

Vitess の安全性

Vitess のみについて、以下を記録します。

• 安全なマイグレーションの状態。
• デプロイリクエストのワークフロー。
• 管理者の承認要件。
• ゲート付きデプロイの使用状況。
• スキーマのリバートが可能かどうか。
• ブランチとキースペースのトポロジー。
• シャーディング／vschema の状態。
• シャーディングされたクエリパターンが関連する vindex を使用しているかどうか。
• バックアップと復元の体制。

エビデンスの形式

すべての所見に、以下のエビデンスを含めます。

• ソース：MCP、CLI、API、ダッシュボードで確認、読み取り専用 SQL、リポジトリのファイル。
• 使用したパスまたはコマンド。
• タイムスタンプ。
• 生の値または簡潔な抜粋。
• 確度：高、中、低。

出力

以下を返します。

• インベントリ表。
• エビデンス不足の表。
• リスクフラグ。
• 次に実行することを推奨するスキル。

次の文で締めくくります。

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