Skip to content
Sarj Sarj Sarj Standards

mixed-migration-phases

Review existing-table migrations that combine backfill, enforcement, and contract phases.

SARJ119 Rule source Tests Catalog JSON

Why

Combining data movement with destructive or enforcing schema changes removes deployment checkpoints and makes lock duration, rollback, and compatibility harder to control.

Fix

Split expand, backfill, enforcement, and contract work into independently deployable migrations, or document why atomic execution is required together with lock, runtime, rollback, and postcondition evidence.

Examples

Before — flagged An existing-table backfill immediately removes its legacy column
migrations/004_credentials.sql
ALTER TABLE credential
ADD COLUMN token TEXT;


UPDATE credential
SET
  token = legacy_token;


ALTER TABLE credential
DROP COLUMN legacy_token;
After — preferred A fresh lookup table is created, seeded, and indexed atomically
migrations/004_status.sql
CREATE TABLE status (id UUID PRIMARY KEY, name TEXT NOT NULL);


INSERT INTO
  status
VALUES
  ('00000000-0000-0000-0000-000000000001', 'ready');


CREATE INDEX status_name_idx ON status (name);