no-long-migration-narration · SQL

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

-- 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

-- 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;

Formerly: excessive-commentary