db-indexing

db-indexing (M11)

インデックス作成は、パフォーマンスとスケーラビリティ（軸 performance）において最も効果の大きい施策です（リレーショナルの重み 20、Indexación）。このモジュールでは、既存のインデックスがデータのクエリ方法に合っているかを確認します。インデックスの不足、順序の不適切さ、型の誤りは、サブミリ秒の検索をシーケンシャルスキャンに変えてしまいます。

チェック項目

1. 複合インデックスの順序（ESR） — 複数列のインデックスでは、列を Equality → Sort → Range の順に並べる必要があります。 先頭に範囲条件や選択性の低い列を置くと、インデックスが無駄になります。
2. カバリング／部分インデックス — 頻繁に実行される SELECT a,b WHERE c には、INCLUDE を使ったカバリングインデックスが有効です。 常に述語で絞り込まれるクエリ（WHERE deleted_at IS NULL）には、部分インデックスが有効です。
3. 特殊な型 — jsonb／配列／全文検索の包含検索には GIN、ジオメトリ／範囲には GiST／SP-GiST、自然順序で追加される列（タイムスタンプ）には BRIN が適しています。通常の B-tree（またはインデックスなし）で処理されている全文検索／地理情報／JSONB のフィルターを検出します。
4. 外部キーにインデックスがない — すべての外部キー列には、カバリングインデックスが必要です。インデックスのない外部キーは、ON DELETE／ON UPDATE 時に参照先で、また結合時にシーケンシャルスキャンを強制します。これは最も効果が高く、リスクが最も低いインデックスに関する指摘です。

スコア／軸

performance のみを対象とします（リレーショナルの Indexación w20、すべての NoSQL プロファイルの Indexación カテゴリー）。

Tier-0（静的解析）

DDL／マイグレーションから宣言済みのインデックスと外部キーを解析し、確認可能なクエリパターン（ORM の where／orderBy、生の SQL）とインデックス列を照合します。一致するインデックスのプレフィックスがない外部キー列、等価条件以外の列が先頭にある複合インデックス、特殊なインデックスのない JSONB／配列／全文検索／地理情報の述語を検出します。インデックスが実際に使用されているかは実行時に確認する必要があるため、Tier-0 では needs_api となります。

Tier-1（検証クエリ）— 外部キーにインデックスがない場合（Postgres）

SELECT conrelid::regclass AS tbl, conname,
       pg_get_constraintdef(c.oid) AS fk
FROM pg_constraint c
WHERE c.contype = 'f'
  AND NOT EXISTS (
    SELECT 1 FROM pg_index i
    WHERE i.indrelid = c.conrelid
      AND (c.conkey[1]) = i.indkey[0]   -- leading index column == first FK column
  );

メソッド index_check。返された各行は、インデックスがないことを確認済みの外部キーです（established）。ESR／カバリングについては、実際のクエリに対する EXPLAIN (ANALYZE, BUFFERS)（メソッド explain_plan、Tier-2）でスキャンの種類を確認します。

指摘事項

schema/finding.schema.json に従って指摘事項を出力します。例：

• M11.orders.customer_id_fk_unindexed — カバリングインデックスのない外部キー列（severity:3、warn、 軸 performance、信頼度は静的解析で directional／Tier-1 で established、fixable: auto — CREATE INDEX CONCURRENTLY）。
• M11.events.composite_order_esr — 複合インデックスの先頭列が範囲条件になっている（severity:2、warn、 directional、fixable: proposed）。
• M11.posts.jsonb_no_gin — GIN インデックスのない jsonb の包含フィルター（severity:3、warn、 directional、fixable: proposed）。

各指摘事項では、evidence.observed に外部キー／インデックスの DDL またはクエリをそのまま引用します。verification.reproduce には、上記のカタログクエリ（外部キーにインデックスがない場合）または $DATABASE_URL を参照する EXPLAIN を記載します。expected_impact は幅のある値と信頼度タグを付けます（根拠のないパーセンテージは禁止）。

正確性

• インデックスがないことが、常に不具合とは限りません。小さな参照テーブルや書き込みの多いテーブルでは、インデックスがある方が遅くなる場合もあります。深刻度はテーブルサイズ／アクセス頻度に応じて設定し、統計情報がなければデフォルトで directional とします。
• レイテンシや行数の改善値を引用してはいけません。影響の大きさは high|medium|low のみで表します。
• 外部キーのインデックス不足には、追加的でノンブロッキング、検証可能な CREATE INDEX CONCURRENTLY を auto で修正可能とします。複合インデックスの順序変更と部分インデックスは、意図が異なる可能性があるため proposed とします。