DB性能検証の初期セットアップ

pre-project setup checklist の一項目。「遅くなってから測る手段を作る」のでは遅いため、繋ぎ込みの実装が始まる前に検証手段を用意しておく。エージェントに実装させる場合はとくに、これがないと「動くが遅い」実装が緑のまま通過する。

なぜ初期に要るのか

機能テストは「動くこと」しか見ない。N+1も全件走査もテストは緑になる
人間のレビューでしか捕まらない失敗モードだが、実行計画は機械可読な形でそれを暴ける
ただし検証手段を後から入れると、既に積み上がった非効率の追認になりやすい

チェックリスト

1. 本番相当のseedデータがあるか

主要テーブルに、本番の桁数に近い件数のseedデータを投入する手段がある
件数だけでなく値の分布が本番に近い（全行同じ値のダミーだと索引の効きが再現しない）
seed投入後に ANALYZE（統計情報の収集）を実行する手順が組み込まれている

これがない状態で性能検証を組んでも、すべてノイズになる。 開発用DBの1000行では全件走査が最速なので、正しい判断が「遅い」と判定される。最初に投資すべきはここ。

2. 合格基準がどこから来ているか

性能要件（レスポンスタイム等）が要求層に書かれている
その数字を誰が決めたかが辿れる（実測値の現状追認になっていない）
書かれていない場合、テストに閾値を書く前に要求側に確認する

「300ms以内」は仕様でも設計でもなく要求の成功基準。エージェントに決めさせると最初の実測値が基準になり、劣化を検出できなくなる。ここは自動化できない。

3. 検証がコマンドとして固定されているか

検証が単一コマンドで実行できる（例: npm run db:check）
判定基準がコード側にあり、プロンプトや指示書側にない
レポート出力があり、before/afterを差分で示せる

指示書に「実行計画を確認せよ」と書くだけでは、エージェントが解釈で基準をずらせる。コマンド化すれば基準の改変が差分に出る。

4. 判定の順序と内容

判定は必ず以下の順序で、上位が失敗したら下位を評価しない。

優先	判定	内容	失敗条件にするか
1	機能テスト	仕様どおり動くこと	必須
2	クエリ発行回数	N+1検出。件数非依存で最も安定	する
3	効率比	返した行数に対し読んだ行数/バッファが異常でないか	する
4	実行時間(ms)	参考値	しない（ログ出力のみ）

機能テストが前段の必須条件になっている
クエリ発行回数の上限が定義されている
効率比の閾値が定義されている（例: 読んだ行数 / 返した行数）
msは記録するが失敗条件にしていない

msを失敗条件にすると誤魔化される。 テストデータを減らす、LIMIT を足す（仕様が変わる）、索引を乱造する（書き込み劣化はこの閾値では見えない）、キャッシュで2回目だけ速くする——どれもmsは改善する。回数と比率は比なので誤魔化せない。

5. アサートしてはいけないもの

実行計画の形（"Index Scan" in output 等）をアサートしていない

計画の形は実装詳細。DBバージョン・統計・データ件数・コストパラメータで変わる。件数が少なければ全件走査を選ぶのが正しいので、このテストは「プランナが正しく判断したとき赤くなる」。宣言的インターフェースのテストで実装詳細を固定している状態。

代わりに安定するもの:

クエリ発行回数（計画非依存）
効率比（件数非依存）
索引が存在することのマイグレーションテスト（「使われるか」ではなく「あるか」）

6. 修正ループの上限とエスカレーション

自動修正ループに回数上限がある（3回程度）
上限超過時に人間へエスカレーションする経路がある

「索引を足せば直る」ケースと「データモデルが間違っている」ケースを、実行計画から区別することはできない。後者を自動修正させると、根本原因の上に索引が積み上がる。

7. 実行レーンの分離

1〜3（速い判定）は通常のテストレーンに置く
本番相当データでのベンチマークは nightly か手動レーンに分離している
ベンチの閾値は絶対時間ではなく前回比の劣化率で見ている

Red-Green-Refactorの内側は「速く・決定的に」が生命線。性能は環境依存で遅いので、内側に置くと開発が止まる。

8. 本番側の恒常観測

遅いクエリを自動記録する設定が入っている
定点観測の手段があり、総実行時間の上位を特定できる

	広く見つける（定点観測）	一点を深く見る（虫眼鏡）
PostgreSQL	`pg_stat_statements` / `auto_explain`	`EXPLAIN (ANALYZE, BUFFERS)`
MongoDB	Database Profiler	`explain("executionStats")`
Elasticsearch	slow log	`?profile=true`

auto_explain.log_min_duration を設定。log_analyze = on は全クエリに計測コストが乗るため、まずoffで始めて段階的に
EXPLAIN ANALYZE は実際に実行する。 UPDATE/DELETE に対しては BEGIN; ... ROLLBACK; で囲む

Elasticsearch固有の注意

ESをデータストアに使う場合、上記の枠組みがそのままは適用できない。

took を単発で判定条件にしていない

フィルタキャッシュ・リクエストキャッシュにより2回目から速くなる。ウォームアップして複数回実行し中央値を取らないと安定しない。RDBMSより「msが揺れる/誤魔化される」度合いが強い。

shard時間は合計ではなく最大値で見ている（遅いshard1枚がレイテンシを決めるため）
rewrite_time の異常を監視している（ワイルドカードや巨大な terms の展開爆発を検出できる）
リクエスト回数を見ている（msearchにまとめられているか＝N+1相当）

補足として、Query DSL側にはコストベースのプランナが存在しない（転置インデックスという単一経路のため選択が発生しない）。「効率比」に相当する指標がprofile出力から素直に取れないので、構造的な指標（書き換え時間・リクエスト回数・対象shard数）に寄せる。

なお _explain APIは1ドキュメントのスコア内訳を出すもので、性能診断用ではない。名前が紛らわしい。