no-migration-comments · SQL

Why

Comments that describe bounds or allowed states leave those invariants unenforced, while SQL CHECK, NOT NULL, UNIQUE and foreign-key constraints reject invalid writes from every caller.

Fix

Express data invariants with SQL constraints and delete explanatory line/block comments and COMMENT ON statements that store prose. COMMENT ON with NULL or an empty string may remove existing comments. Put deployment context in the change description. Retain only executable runner, dialect, statement-boundary directives, and scoped timeout-justification directives bound to a matching timeout statement. Migration sarj-noqa comments are also reported.

Examples

Before — flagged A comment cannot enforce a column range

CREATE TABLE IF NOT EXISTS settings (retries INTEGER);

-- retries must be positive

After — preferred SQL enforces the bound while runner directives remain executable

-- migrate:up
CREATE TABLE IF NOT EXISTS settings (retries INTEGER CHECK (retries > 0));

-- migrate:down
DROP TABLE IF EXISTS settings;

Before — flagged Remove an empty comment while keeping SQL tokens separate

SELECT
  1 /**/ AS value;

After — preferred Whitespace preserves the executable SQL after the comment is removed

SELECT
  1 AS value;

Autofix output

SELECT
  1 AS value;

Before — flagged Remove an empty comment beside string data

SELECT
  'payload' AS label,
  1 /**/ AS value;

After — preferred String data and SQL tokens remain unchanged

SELECT
  'payload' AS label,
  1 AS value;

Autofix output

SELECT
  'payload' AS label,
  1 AS value;

Before — flagged Remove a proven disabled statement without changing executable SQL

-- DROP TABLE legacy;
SELECT
  1;

After — preferred Executable SQL remains after removing the inert comment

SELECT
  1;

Autofix output

SELECT
  1;