planetscale-schema-recommendations-agent-loop

スキーマ推奨事項のエージェントループ

目的

PlanetScale のスキーマ推奨事項を、高品質なエージェントへの入力として使用します。推奨事項を、安全な実装計画、イシュー、ブランチ、マイグレーション、またはプルリクエストに変換します。推奨事項を直接適用してはいけません。

入力

以下を収集します。

• 未解決のスキーマ推奨事項。
• 推奨事項の種類。
• 影響を受けるテーブル、キースペース、スキーマ、クエリパターン。
• 提案された DDL。
• 裏付けとなる Insights の根拠。
• アプリケーションのリポジトリとマイグレーションシステム。
• エンジン：Vitess または Postgres。
• 対象ブランチ。

認識すべき推奨事項の種類

• 非効率なクエリに対するインデックスの追加。
• 冗長なインデックスの削除。
• 主キー ID の枯渇防止。
• 未使用テーブルの削除。
• レガシーの文字セットまたは照合順序のアップグレード。
• その他の DDL に関する推奨事項。

トリアージの質問

各推奨事項について、以下に回答します。

• これは現在も未解決で、関連性がありますか？
• どのクエリパターンがこれを引き起こしましたか？
• それらのクエリを生成するアプリケーションのコードパスはどれですか？
• 推奨事項は、アプリケーションのマイグレーションフレームワークで安全に表現できますか？
• ORM／スキーマの信頼できる情報源を変更する必要がありますか？
• 本番環境以外のブランチでテストできますか？
• 読み取り、書き込み、ストレージ、デプロイ時間への予想される影響は何ですか？
• ロールバックまたは差し戻しの手段はありますか？
• 競合する推奨事項またはマイグレーションはありますか？

エンジン固有の実装パス

Vitess

推奨パス：

1. 開発ブランチを作成するか、既存のものを使用します。
2. 承認後に限り、そのブランチにスキーマ変更を適用します。
3. 承認後に限り、デプロイリクエストを作成します。
4. デプロイリクエストのレビューで、スキーマ、シャードへの影響、データ損失に関する警告、lint エラー、競合を確認します。
5. 即時デプロイが明確に正当化される場合を除き、通常の安全なマイグレーションパスを使用します。
6. 承認後に限り、デプロイします。
7. デプロイ後に Insights と異常状態を監視します。

承認前のデフォルトの出力：稼働中のデプロイリクエストではなく、マイグレーション提案を含むイシューまたは PR。

Postgres

推奨パス：

1. 可能であれば、DDL をアプリケーションのマイグレーションフレームワークに変換します。
2. 本番環境以外のブランチでテストします。
3. アプリケーションのテストと、関連するクエリのチェックを実行します。
4. PR を作成します。
5. 承認後に限り、本番マイグレーションを適用します。
6. バックアップ／PITR ランブックを復旧計画として使用します。マイグレーションレビューの代わりにしてはいけません。

承認前のデフォルトの出力：本番 DDL ではなく、マイグレーション PR またはイシュー。

コードベースとの関連付け

リポジトリを利用できる場合：

• テーブル名とカラム名を検索します。
• ORM モデル定義を検索します。
• マイグレーションを検索します。
• Insights に記載されたクエリフィンガープリント、ルートタグ、ジョブ名、コントローラー／アクション名を検索します。
• 推奨事項をデータベース DDL、ORM スキーマ、未加工のマイグレーション、アプリケーションのクエリコードのどれに実装すべきかを特定します。

実装を提案する前の安全性チェック

以下の場合は、直接の適用を禁止します。

• 推奨事項が古い、またはすでに対応済みの場合。
• 影響を受けるテーブルが小さく、メリットが不明確な場合。
• 既存のインデックスと重複するインデックスを追加する場合。
• 読み取りのメリットが不十分なまま、書き込み負荷の高いワークロードに悪影響を及ぼすインデックスを追加する場合。
• テーブルが未使用に見えるものの、リポジトリ内の参照が曖昧な場合。
• テーブルまたはインデックスの削除について、所有者の確認が得られていない場合。
• マイグレーションフレームワークで別のスキーマ情報源が信頼されている場合。
• 推奨事項が本番環境を対象としており、ブランチ／テスト計画がない場合。

出力

各推奨事項について、以下を作成します。

• 推奨事項 ID／番号。
• 種類。
• 重大度と予想されるメリット。
• Insights の根拠。
• 影響を受けるスキーマ。
• 提案された DDL。
• アプリケーションコードの担当者または該当しそうな場所。
• 安全な実装パス。
• 検証計画。
• ロールバック／差し戻し計画。
• 必要な承認。

最後に、以下を記載します。

「スキーマ推奨事項は適用されていません。」