Skip to content
Sarj Code Standards

no-long-migration-narration

Long migration comments narrate implementation instead of recording durable constraints.

SARJ115 Rule source Tests Catalog JSON

Why

Step-by-step prose duplicates nearby DDL and drifts as statements change; migrations should be readable from SQL plus concise operational constraints.

Fix

Delete implementation narration. Keep only concrete rollback, locking, data-loss, compatibility, security, or externally owned constraints that the DDL cannot express.

Examples

Before — flagged Migration comments narrate the table declarations
migrations/001.sql
-- Create the custom_integration table used by the application.
-- The table stores each configured integration for an organization.
-- The next statement defines its identifier and display name.
-- The final statement creates those columns in the database.
CREATE TABLE IF NOT EXISTS integration (id BIGINT PRIMARY KEY, name TEXT);
After — preferred Concrete operational constraints remain local
migrations/001.sql
-- Backfill no more than 1000 rows per transaction.
-- Keep lock_timeout at 3 seconds while API-812 writes continuously.
-- Wait for replica lag to return below 500 ms before the next batch.
-- Roll back by dropping the new index concurrently.
SET
  lock_timeout = '3s';


SELECT
  1;
Before — flagged A long run consists entirely of disabled SQL declarations
migrations/001.sql
-- CREATE TABLE users (id BIGINT PRIMARY KEY, name TEXT);
-- CREATE TABLE groups (id BIGINT PRIMARY KEY, name TEXT);
-- CREATE TABLE teams (id BIGINT PRIMARY KEY, name TEXT);
-- CREATE TABLE accounts (id BIGINT PRIMARY KEY, name TEXT);
After — preferred Executable declarations do not narrate disabled source
migrations/001.sql
CREATE TABLE users (id BIGINT PRIMARY KEY, name TEXT);


CREATE TABLE groups (id BIGINT PRIMARY KEY, name TEXT);


CREATE TABLE teams (id BIGINT PRIMARY KEY, name TEXT);


CREATE TABLE accounts (id BIGINT PRIMARY KEY, name TEXT);

Formerly: excessive-commentary