Skip to content
Sarj Sarj Sarj Standards

excess-migration-index-requires-justification

Require a structured local justification for excess explicit indexes in an authored migration.

SARJ116 Rule source Tests Catalog JSON

Why

Every explicit index adds write amplification, storage, vacuum work, and planner surface; bursts of indexes often encode unmeasured read paths in the transactional database.

Fix

Keep at most three explicit indexes per table and eight per migration, or place an exact index-justification: app-read: ...; query: path#symbol; explain: URL or index-justification: referential-action: ... comment immediately above each excess index. For CREATE UNIQUE INDEX only, index-justification: uniqueness-constraint: ...; ticket: ABC-123 is also accepted.

Examples

Before — flagged A fourth explicit index has no local justification
migrations/004_indexes.sql
CREATE INDEX a_idx ON event (a);


CREATE INDEX b_idx ON event (b);


CREATE INDEX c_idx ON event (c);


CREATE INDEX d_idx ON event (d);
After — preferred An excess index names its application read and durable ticket
migrations/004_indexes.sql
CREATE INDEX a_idx ON event (a);


CREATE INDEX b_idx ON event (b);


CREATE INDEX c_idx ON event (c);


-- index-justification: app-read: event delivery queue; query: app/event_store.py#claim; explain: https://metrics.example.test/plans/812
CREATE INDEX d_idx ON event (d);

Formerly: index-budget