process-db-report

データベースパフォーマンスレポートの処理

データベースの可観測性レポートを分析し、Drizzle ORM のコードベース向けに優先順位を付けた最適化計画を作成します。

トリアージのワークフロー

1. レポートを解析する — 貼り付けられた可観測性レポートから構造化データを抽出します。
2. レポートの完全性を検証する — 推奨事項を作成する前に、不足しているセクションを特定します。
3. 問題を分析する — 根拠に基づくルールを使って、影響の大きい問題を検出します。
4. 優先順位を付ける — 影響度（高・中・低）に基づいて問題を並べ替えます。
5. アクションプランを作成する — スキーマレベルの指針を含む、具体的で安全なタスクを提案します。

不完全なレポートの扱い

• 必要なデータがない場合は推測せず、不足しているセクションを求めます。
• 推奨事項の作成が妨げられている場合に限り、必要な不足部分を求めます。
• 部分的なデータが利用できる場合、推奨事項には条件付きであることを明記します。

トリアージを完全に行うために必要なセクション：

• テーブル統計
• 高頻度のシーケンシャルスキャン
• 未使用／使用頻度の低いインデックス
• インデックスのない外部キー
• キャッシュヒット率

---

問題検出のヒューリスティクス

重大な問題（即時対応）

問題	検出ルール	対応
肥大化したテーブル	テーブル統計の不要行が10%を超える	/app/admin/observability UI から VACUUM を実行
インデックスの不足／カバレッジ不足	インデックスの使用率が50%未満で、高頻度のシーケンシャルスキャンがあり、クエリの既知のフィルター／ソートパターンがある	クエリパターンを検証してから、packages/db/src/schema.ts にインデックス戦略を提案します
インデックスのない外部キー	対応するインデックスのない外部キー列	schema.ts にインデックスを追加

優先度：中（次のスプリント）

問題	検出ルール	対応
未使用のインデックス	定義されたワークロード期間において使用率の低い非ユニークインデックス	実際のクエリパスと安全性の確認を行ってから、schema.ts から削除します
重複インデックス	同じ列をカバーする複数のインデックス	冗長なインデックスを削除します

優先度：低（監視）

問題	検出ルール	対応
キャッシュヒット率	99%未満	まずワークロードとキャッシュの動作を調査します。必要に応じて、インフラレベルの追加対応として shared_buffers の調整に進みます

---

想定されるレポート形式

Table Statistics:
| table_name | total_size | dead_rows | dead_ratio_pct |
|------------|------------|-----------|----------------|
| users      | 2048 MB    | 15000     | 12.5           |

High Sequential Scans:
| table_name | sequential_scans | index_usage_pct |
|------------|------------------|-----------------|
| sessions   | 45000            | 25              |

Unused/Rarely Used Indexes:
| index_name           | times_used | index_size |
|---------------------|------------|------------|
| idx_old_feature     | 2          | 5 MB       |

Foreign Keys Without Indexes:
| table_name | column_name | suggested_index |
|------------|-------------|-----------------|
| posts      | user_id     | CREATE INDEX... |

Cache Hit Ratio:
| cache_hit_ratio_pct |
|---------------------|
| 97.5                |

---

インデックスの安全性に関するルール

次のインデックスは絶対に削除しないでください。

• 主キー（*_pkey）
• 一意制約（*_unique）
• ビジネスロジックの制約（例：organizations_slug_unique）

削除しても安全なインデックス：

• 代表的なワークロード期間（トラフィックパターンに応じて、たとえば7～30日間）を通して使用頻度が一貫して低い一意でないインデックス
• 冗長なインデックス（複合インデックスでカバーされているもの）

削除時に必須の確認事項：

• インデックスが未使用と判断する前に、ワークロード期間が十分にカバーされていることを確認してください。
• 削除前に、実際のアプリケーションパス（APIエンドポイント、バックグラウンドジョブ、cronのフロー）からのクエリパスの使用状況を確認してください。
• 制約、マイグレーション、運用ワークフローを通じた隠れた依存関係がないことを確認してください。
• クエリパスの検証データがない場合は、条件付きの推奨にとどめてください。

安全に削除できる例：

// oauth_consents has composite unique(userId, clientId)
// So single-column index on clientId alone is redundant
index("oauth_consents_client_id_idx"); // SAFE TO REMOVE

---

アクションプランのテンプレート

完全な出力構成と文言については、references/action-plan-template.mdを読み込み、それに従ってください。

---

重要なルール

• 実際のファイルパスを参照してください（packages/db/src/schema.ts）
• スキーマ変更には正確なコードスニペットを提示してください
• 影響度の高い順に優先してください（削除可能な行 > 不足しているインデックス > 未使用のインデックス）
• アドホックなSQLは絶対に提案しないでください — 正式なソースはschema.tsです
• 最後にワークフローの手順を含めてください
• 正当な根拠を示せるだけのデータがレポートにある場合に限り、改善を推定してください
• shared_buffersの調整は任意とし、エスカレーション時のみのインフラに関するガイダンスとして扱ってください

---

関連スキル

• performance-optimization — Effectの並列処理パターン、N+1の修正、バッチ処理
• drizzle-database — スキーマパターン、マイグレーション、リレーション
• production-troubleshooting — Kubernetesのパフォーマンスデバッグ