Skip to content
Sarj Code Standards

migration-timeout-requires-justification

Require an explicit operational reason for migration timeout settings.

SARJ131 Rule source Tests Catalog JSON

Why

Routine SET/RESET timeout headers duplicate session policy and change migration failure behavior without recording why a migration needs a different deadline or lock wait.

Fix

Review and remove unnecessary timeout bookkeeping, or put a standalone -- timeout-justification: <setting> -- <operational reason> immediately before each justified statement. The setting must match; reviewers assess the reason. Do not remove a timeout merely because its reason is missing.

Examples

Before — flagged A reset also changes the session's timeout behavior
migrations/001.sql
RESET lock_timeout;
After — preferred Cleanup records the setting it restores
migrations/001.sql
-- timeout-justification: lock_timeout -- restore the session default after the reviewed lock override
RESET lock_timeout;
Before — flagged A timeout header has no operational reason
migrations/001.sql
SET
  statement_timeout = '10min';
After — preferred The reviewed backfill records why it needs a different deadline
migrations/001.sql
-- timeout-justification: statement_timeout -- bounded backfill exceeds the session default
SET
  statement_timeout = '10min';