vanara 0.1.0 → 0.2.0

package/catalog/skills/database-migrations/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: database-migrations
+description: How to write safe, reversible, zero-downtime database schema migrations — additive-first changes, the expand/migrate/contract pattern, batched backfills, concurrent index builds, safe NOT NULL, rollbacks, and the locking pitfalls that cause outages. A deep reference with runnable checks.
+type: skill
+version: 2.0.0
+updated: 2026-06-29
+---
+# Database Migrations
+
+A migration runs against **live data while old code may still be serving traffic**. The dangerous moment
+is never the steady state before or after — it's the in-between, when the schema has changed but not every
+app instance has. Design every change to be correct *during* that window. Heavy detail lives in
+`references/`; copy-paste material in `examples/`; a runnable safety check in `scripts/`.
+
+## Mental model
+
+Two things deploy on different clocks: your **schema** (one atomic change) and your **code** (rolled out
+instance-by-instance over minutes). A migration is safe only if **both the old and new code work against
+both the old and new schema** for the overlap window. That single rule explains almost every practice
+below.
+
+| Concern | Safe answer |
+|---|---|
+| What changed | the smallest possible step |
+| When old code sees it | it must still work (backward-compatible) |
+| Locks held | none long enough to block traffic |
+| If it goes wrong | a tested, reversible path back |
+| Big rename/retype | expand → migrate → contract, across deploys |
+
+## 1. Additive-first
+
+Prefer **additive, backward-compatible** changes. Adding a nullable column, adding a table, or adding an
+index never breaks code that doesn't know about it. Destructive changes (drop/rename column, change type,
+add `NOT NULL`) break the old code still running mid-deploy, so they must be sequenced — see §3.
+
+```sql
+-- SAFE: old code ignores the new column; new code can start using it.
+ALTER TABLE users ADD COLUMN email_verified_at timestamptz NULL;
+
+-- UNSAFE in one step: old code still INSERTs rows without this column.
+ALTER TABLE users ADD COLUMN email_verified_at timestamptz NOT NULL;
+```
+
+## 2. Never hold a long lock
+
+Most outages from migrations are **lock waits**, not data loss. A statement that rewrites a table or takes
+an `ACCESS EXCLUSIVE` lock blocks every read/write behind it, and that queue backs up into your connection
+pool within seconds.
+
+- Add columns as **nullable** (or with a constant default — on modern Postgres a constant default is
+  metadata-only and does not rewrite the table; a *volatile* default does).
+- Build indexes with `CREATE INDEX CONCURRENTLY` (no table rewrite, no write lock — but it can't run
+  inside a transaction).
+- **Backfill in batches** with short transactions, not one giant `UPDATE` that locks every row.
+- Set a `lock_timeout` so a migration that *can't* get its lock fails fast instead of stalling traffic.
+
+```sql
+SET lock_timeout = '3s';            -- fail fast rather than queue behind traffic
+CREATE INDEX CONCURRENTLY idx_orders_status ON orders (status);
+```
+
+Full catalogue of which operations rewrite/lock and the safe alternative: `references/zero-downtime-changes.md`.
+
+## 3. Expand / migrate / contract
+
+The core pattern for any breaking change (rename, retype, split, add `NOT NULL`) without downtime. It
+spreads one logical change across **multiple deploys** so old and new code always overlap safely:
+
+1. **Expand** — add the new shape (nullable column / new table / new index). Backward-compatible.
+2. **Migrate** — deploy code that **dual-writes** old+new, then **backfill** existing rows in batches,
+   then switch **reads** to the new shape and verify.
+3. **Contract** — once nothing reads or writes the old shape, drop it in a *later* deploy.
+
+Each step is independently deployable and independently reversible. The full worked walkthrough
+(including a column rename and a non-null-ification) is in `references/expand-contract.md`.
+
+## 4. Reversibility & safety
+
+Every migration should declare how to undo it. Some operations are **irreversible** in practice
+(`DROP COLUMN`, `DROP TABLE`, `TRUNCATE` destroy data; a down-migration can recreate the *structure* but
+not the *data*). Treat those specially:
+
+- Provide a real `down` for reversible ops; for irreversible ones, document that recovery is **restore from
+  backup**, and take a verified backup/snapshot immediately before.
+- Separate the destructive `contract` step into its own migration so you can ship the safe parts and pause.
+- Dry-run on a production-like copy and **time it** — a 30-minute backfill on staging may be hours in prod.
+
+Reversible-vs-irreversible rules, backup checklists, and dry-run guidance: `references/rollback-and-safety.md`.
+Validate a `.sql` file with `scripts/check-migration-reversible.mjs` before shipping.
+
+## 5. Operational discipline
+
+- **One concern per migration.** Mixing a schema change and a data backfill in one file makes rollback
+  ambiguous and the transaction huge.
+- **Forward-only in production.** Prefer rolling *forward* with a fix over rolling back a migration that
+  already ran against live data; keep `down` for local/staging and emergencies.
+- **Idempotent where possible** (`IF NOT EXISTS`, `IF EXISTS`) so a retried run after a partial failure
+  doesn't error.
+- **Backfills run outside the schema transaction**, in batches with a sleep, so they don't hold locks or
+  bloat WAL/replication lag.
+
+## Common pitfalls (failure modes)
+
+- **`NOT NULL` in one shot** — adds a column the still-running old code inserts NULLs into, *or* triggers a
+  full validating scan. Add nullable, backfill, then `SET NOT NULL` (validate via a `CHECK ... NOT VALID`
+  then `VALIDATE`). See the zero-downtime reference.
+- **Plain `CREATE INDEX`** on a hot table — takes a write lock for the whole build. Use `CONCURRENTLY`.
+- **One giant `UPDATE` backfill** — locks millions of rows, blocks writes, balloons WAL. Batch it.
+- **Rename a column in one deploy** — old code references the old name and 500s during the rollout window.
+  Use expand/contract.
+- **Volatile/changing default on add-column** — forces a full table rewrite under an exclusive lock.
+- **No `lock_timeout`** — the migration silently queues behind a long transaction and takes the app down.
+- **Destructive `down` that "reverses" a drop** — it recreates an empty column; the data is gone. Mark it
+  irreversible and rely on backups.
+
+## When NOT to use / trade-offs
+
+- **Tiny project, maintenance window available.** If you can take 5 minutes of downtime at 3am and the
+  table is small, a single blocking `ALTER` is simpler and cheaper than a three-deploy expand/contract.
+  Zero-downtime machinery is overhead you only need at scale or with strict SLAs.
+- **Throwaway / pre-launch schemas** with no real data — just recreate the schema; migrations add ceremony
+  you don't need yet.
+- **NoSQL / schemaless stores** shift the work to the application (versioned documents, read-time
+  migration) rather than DDL — the expand/contract *idea* still applies, the SQL specifics don't.
+- **Data migrations vs schema migrations** are different beasts; heavy data reshaping often belongs in a
+  background job, not a migration runner that blocks deploys.
+
+## Files in this package
+
+- `references/expand-contract.md` — the expand/migrate/contract pattern, worked end-to-end
+- `references/zero-downtime-changes.md` — per-operation safe recipes (add column, backfill, index, NOT NULL)
+- `references/rollback-and-safety.md` — reversible vs irreversible ops, backups, dry-runs
+- `examples/add-column-safe.sql` — a safe, batched, reversible migration
+- `examples/migration-config.example.json` — a migration runner config with safety guardrails
+- `scripts/check-migration-reversible.mjs` — Node check that flags irreversible SQL + missing down-migrations
+
+Pairs with the `database-scaling` skill, the `data-modeling` skill, and the `database-reviewer` agent.

package/catalog/skills/database-migrations/examples/add-column-safe.sql

@@ -0,0 +1,34 @@
+-- Safe, batched, reversible migration: add orders.priority with a backfill.
+-- Demonstrates: fail-fast lock, additive nullable add, batched backfill outside
+-- the schema transaction, NOT NULL via validated CHECK, and a real down-migration.
+--
+-- == UP =====================================================================
+
+-- Fail fast instead of queueing behind live traffic.
+SET lock_timeout = '3s';
+
+-- Step 1 (Expand): additive, nullable, metadata-only. Old code is unaffected.
+ALTER TABLE orders ADD COLUMN IF NOT EXISTS priority int NULL;
+
+-- Step 2 (Migrate): backfill existing rows in bounded batches.
+-- Run this loop in the app/runner, NOT in the schema transaction, committing
+-- between batches. Repeat until 0 rows are affected. WHERE ... IS NULL makes it
+-- idempotent and resumable after a partial failure.
+--   UPDATE orders
+--   SET priority = 0
+--   WHERE id IN (
+--     SELECT id FROM orders WHERE priority IS NULL ORDER BY id LIMIT 5000
+--   );
+
+-- Step 3: enforce NOT NULL without a blocking validating scan.
+ALTER TABLE orders
+  ADD CONSTRAINT orders_priority_nn CHECK (priority IS NOT NULL) NOT VALID;
+-- After the backfill confirms no NULLs remain:
+ALTER TABLE orders VALIDATE CONSTRAINT orders_priority_nn;
+
+-- == DOWN ===================================================================
+-- Reversible: the column was newly added and the constraint is ours to drop.
+-- No data loss, because nothing depended on this column before this migration.
+
+ALTER TABLE orders DROP CONSTRAINT IF EXISTS orders_priority_nn;
+ALTER TABLE orders DROP COLUMN IF EXISTS priority;

package/catalog/skills/database-migrations/examples/migration-config.example.json

@@ -0,0 +1,27 @@
+{
+  "$comment": "Example migration-runner config with safety guardrails. No secrets: the connection comes from an env var, never hardcoded.",
+  "databaseUrlEnv": "DATABASE_URL",
+  "migrationsDir": "./migrations",
+  "migrationsTable": "schema_migrations",
+  "direction": "up",
+  "safety": {
+    "lockTimeout": "3s",
+    "statementTimeout": "0",
+    "requireDownMigration": true,
+    "transactionPerMigration": true,
+    "disableTransactionForConcurrent": true,
+    "blockIrreversibleWithoutAck": true,
+    "irreversibleStatements": ["DROP COLUMN", "DROP TABLE", "TRUNCATE"]
+  },
+  "backfill": {
+    "runOutsideSchemaTransaction": true,
+    "batchSize": 5000,
+    "sleepMsBetweenBatches": 100,
+    "resumeWhere": "col IS NULL"
+  },
+  "verification": {
+    "dryRunOnCopy": true,
+    "requireBackupBeforeDestructive": true,
+    "checkScript": "node ../scripts/check-migration-reversible.mjs"
+  }
+}

package/catalog/skills/database-migrations/references/expand-contract.md

@@ -0,0 +1,74 @@
+# Expand / Migrate / Contract
+
+The pattern for making a breaking schema change with **zero downtime**. The insight: you cannot atomically
+change schema *and* code together, so you split one logical change into a sequence of backward-compatible
+deploys where old and new code always coexist safely.
+
+## The three phases
+
+1. **Expand** — additively introduce the new shape. The schema now supports *both* old and new. Old code
+   is untouched; new code can begin targeting the new shape. This phase is always backward-compatible.
+2. **Migrate** — get all data and all traffic onto the new shape:
+   - deploy code that **dual-writes** (writes both old and new),
+   - **backfill** existing rows in batches,
+   - switch **reads** to the new shape and verify metrics/parity,
+   - stop writing the old shape.
+3. **Contract** — once nothing reads or writes the old shape, **remove it** in a later, separate deploy.
+
+Each step is independently shippable and reversible until the final destructive contract.
+
+## Worked example: rename `users.email` → `users.email_address`
+
+A column rename in one statement breaks every still-running old instance the moment it lands. Spread it out:
+
+### Deploy 1 — Expand
+```sql
+ALTER TABLE users ADD COLUMN email_address text NULL;
+```
+Old code ignores the new column; nothing breaks.
+
+### Deploy 2 — Migrate
+App code now writes **both** columns on every insert/update (dual-write). Backfill the old rows in batches
+(see `zero-downtime-changes.md` for the batching loop):
+```sql
+UPDATE users
+SET email_address = email
+WHERE email_address IS NULL
+  AND id BETWEEN :lo AND :hi;   -- repeat across id ranges
+```
+Then switch reads to `email_address`, verify parity (counts match, no NULLs where there shouldn't be), and
+stop writing `email`.
+
+### Deploy 3 — Contract
+Only after every instance has stopped using `email`:
+```sql
+ALTER TABLE users DROP COLUMN email;
+```
+This is the one irreversible step — gate it behind a verified backup.
+
+## Worked example: making a column `NOT NULL`
+
+You cannot just `SET NOT NULL` on a populated table serving traffic — old code may still insert NULLs, and
+the validating scan takes a lock.
+
+1. **Expand:** add a `CHECK (col IS NOT NULL) NOT VALID` constraint — this applies to *new* rows only and
+   takes no validating scan.
+2. **Migrate:** deploy code that always sets the column; backfill existing NULLs in batches; then
+   `ALTER TABLE t VALIDATE CONSTRAINT ...` (scans without an exclusive lock).
+3. **Contract:** optionally replace with a real `SET NOT NULL` now that the data is clean, or keep the
+   validated CHECK.
+
+## Why each phase is reversible
+
+- After Expand, drop the new (empty) column — no data lost.
+- During Migrate, revert reads to the old column — both are still populated by dual-write.
+- Only Contract is destructive, which is exactly why it lives in its own deploy that you can delay.
+
+## Checklist
+
+- [ ] New shape added nullable / non-blocking
+- [ ] Dual-write deployed and confirmed on every instance
+- [ ] Backfill complete and verified (no missing rows)
+- [ ] Reads switched and validated against metrics
+- [ ] Old-shape writes stopped everywhere
+- [ ] Backup taken before the contract/drop

package/catalog/skills/database-migrations/references/rollback-and-safety.md

@@ -0,0 +1,71 @@
+# Rollback & Safety
+
+How to make migrations recoverable, and how to handle the changes that *can't* be cleanly undone.
+
+## Reversible vs irreversible
+
+A migration's `down` should restore the prior state. But "reverse the DDL" is not the same as "restore the
+data." Classify every change:
+
+| Operation | Reversible? | Notes |
+|---|---|---|
+| ADD COLUMN | yes | `down` = DROP COLUMN (the column was empty/new) |
+| CREATE TABLE / INDEX | yes | `down` = DROP it |
+| ADD CONSTRAINT | yes | `down` = DROP CONSTRAINT |
+| DROP COLUMN | **no** | `down` recreates *structure*, not the deleted data |
+| DROP TABLE | **no** | data is gone; only a backup restores it |
+| TRUNCATE | **no** | not a schema change at all; deletes all rows irrecoverably |
+| Type change with data loss | **no** | narrowing/casting can lose precision |
+
+For irreversible operations, a fake "reversing" `down` is *worse than none* — it gives false confidence
+while the data is already lost. Mark them explicitly irreversible and rely on backups.
+
+## The backup rule
+
+Before any **destructive** migration (drop/truncate/lossy type change):
+
+1. Take a verified backup or snapshot **immediately before** the migration (point-in-time recovery window
+   confirmed, or a fresh logical/physical dump).
+2. Confirm you can actually restore it (an untested backup is a hope, not a plan).
+3. Run the destructive step in its **own migration**, separate from non-destructive work, so a rollback of
+   the safe parts doesn't force you to touch the dangerous one.
+
+## Forward-fix over rollback
+
+In production, rolling *back* a migration that already ran against live data is often more dangerous than
+rolling *forward* with a corrective migration. Reasons:
+
+- The `down` may itself be slow/locking on a now-larger table.
+- Code already deployed may depend on the new schema.
+- Reverting can discard data written since the migration ran.
+
+Keep `down` migrations for local dev and staging; in prod, prefer a new forward migration that fixes the
+problem. Design changes (via expand/contract) so a forward fix is always available.
+
+## Dry-run discipline
+
+- Run the migration on a **production-like copy** (similar row counts, indexes, and load), not an empty dev
+  DB.
+- **Time it.** A backfill that takes 30s on 10k staging rows can take hours on 50M prod rows.
+- Watch lock waits and replication lag during the dry run; that's where surprises hide.
+- For long backfills, prove the batch loop terminates and that a mid-run failure can be safely resumed
+  (idempotent: `WHERE col IS NULL`).
+
+## Idempotency & partial failure
+
+A migration may die halfway (timeout, deploy abort). Make re-runs safe:
+
+```sql
+ALTER TABLE orders ADD COLUMN IF NOT EXISTS priority int NULL;
+DROP INDEX IF EXISTS idx_orders_old;
+```
+Backfills keyed on `WHERE col IS NULL` naturally resume from where they stopped.
+
+## Pre-ship checklist
+
+- [ ] Every step classified reversible or irreversible
+- [ ] `down` provided for reversible steps; irreversible ones flagged, not faked
+- [ ] Destructive steps isolated in their own migration
+- [ ] Verified backup taken before destructive changes
+- [ ] Dry-run on prod-like data, timed, lock/lag observed
+- [ ] Re-run is idempotent / resumable

package/catalog/skills/database-migrations/references/zero-downtime-changes.md

@@ -0,0 +1,84 @@
+# Zero-Downtime Change Recipes
+
+Per-operation guidance: which DDL is safe, which rewrites/locks the table, and the safe alternative.
+Examples use PostgreSQL syntax; the *principles* (don't hold long locks, batch backfills, additive-first)
+apply to MySQL/MariaDB too, though the exact lock behaviour differs by engine and version.
+
+## Add a column
+
+```sql
+-- SAFE: nullable add is metadata-only.
+ALTER TABLE orders ADD COLUMN priority int NULL;
+
+-- SAFE on modern Postgres: a CONSTANT default is metadata-only (no rewrite).
+ALTER TABLE orders ADD COLUMN status text NOT NULL DEFAULT 'open';
+
+-- UNSAFE: a VOLATILE default forces a full table rewrite under an exclusive lock.
+ALTER TABLE orders ADD COLUMN token uuid NOT NULL DEFAULT gen_random_uuid();
+```
+For a volatile default: add the column nullable, backfill in batches, then add the default + NOT NULL.
+
+## Backfill in batches
+
+Never `UPDATE` an entire large table in one statement — it locks every touched row, blocks writes, and
+bloats WAL/replication lag. Loop in bounded chunks with short transactions:
+
+```sql
+-- Run repeatedly (in the app or a job) until 0 rows are affected.
+UPDATE orders
+SET priority = 0
+WHERE priority IS NULL
+  AND id IN (
+    SELECT id FROM orders WHERE priority IS NULL ORDER BY id LIMIT 5000
+  );
+-- COMMIT between batches; optionally sleep to ease replica lag.
+```
+Keep batches small enough that each transaction is sub-second. Backfills belong **outside** the schema
+migration transaction.
+
+## Create an index
+
+```sql
+-- UNSAFE: plain CREATE INDEX takes a write lock for the whole build.
+CREATE INDEX idx_orders_status ON orders (status);
+
+-- SAFE: CONCURRENTLY builds without blocking reads/writes.
+-- Caveat: cannot run inside a transaction, and a failure leaves an INVALID index to drop & retry.
+CREATE INDEX CONCURRENTLY idx_orders_status ON orders (status);
+```
+After a failed concurrent build: `DROP INDEX CONCURRENTLY idx_orders_status;` then retry.
+
+## Add NOT NULL safely
+
+```sql
+-- Step 1: validate new rows only, no scan, no exclusive lock.
+ALTER TABLE users ADD CONSTRAINT users_email_nn CHECK (email IS NOT NULL) NOT VALID;
+-- Step 2: backfill NULLs in batches (see above).
+-- Step 3: validate existing rows without an exclusive lock.
+ALTER TABLE users VALIDATE CONSTRAINT users_email_nn;
+```
+
+## Set lock_timeout
+
+```sql
+-- Make a migration that can't acquire its lock fail fast instead of queueing behind traffic.
+SET lock_timeout = '3s';
+SET statement_timeout = '0';   -- but let a long CONCURRENTLY build run
+```
+
+## Drop / rename — never one-shot in production
+
+`DROP COLUMN`, `RENAME COLUMN`, and type changes break still-running old code. Route them through
+expand/contract (`expand-contract.md`). A drop is destructive — gate it behind a backup.
+
+## Quick reference
+
+| Operation | One-shot safe? | Safe approach |
+|---|---|---|
+| Add nullable column | yes | direct |
+| Add column w/ constant default | yes (modern PG) | direct |
+| Add column w/ volatile default | no | nullable → backfill → default |
+| Create index | no | `CONCURRENTLY` |
+| Add NOT NULL | no | CHECK NOT VALID → backfill → VALIDATE |
+| Rename / drop column | no | expand/contract |
+| Change column type | no | new column + backfill + swap |

package/catalog/skills/database-migrations/scripts/check-migration-reversible.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// Runnable check: scans a migration's SQL text for safety problems —
+//   1. irreversible statements (DROP COLUMN/TABLE, TRUNCATE) that destroy data
+//   2. missing a down-migration (no "-- DOWN" / "== DOWN" section)
+//   3. risky operations that should be made non-blocking (plain CREATE INDEX)
+//
+// Usage:
+//   node check-migration-reversible.mjs path/to/migration.sql
+//   cat migration.sql | node check-migration-reversible.mjs
+//   node check-migration-reversible.mjs --selftest    # built-in test cases
+//
+// Exit code: 0 = no blocking issues, 1 = blocking issue (or selftest failed).
+
+import { readFileSync } from 'node:fs';
+
+const IRREVERSIBLE = [
+  [/\bDROP\s+COLUMN\b/i, 'DROP COLUMN destroys data — irreversible; isolate it and back up first'],
+  [/\bDROP\s+TABLE\b/i, 'DROP TABLE destroys data — irreversible; back up before running'],
+  [/\bTRUNCATE\b/i, 'TRUNCATE deletes all rows irrecoverably — irreversible'],
+];
+
+const WARNINGS = [
+  [/\bCREATE\s+INDEX\b(?!\s+CONCURRENTLY)(?![^\n]*CONCURRENTLY)/i,
+    'plain CREATE INDEX locks the table — prefer CREATE INDEX CONCURRENTLY'],
+];
+
+// Strip line/block comments so a statement mentioned in a comment isn't flagged,
+// but keep section markers detectable separately (we test the raw text for those).
+function stripComments(sql) {
+  return sql
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')   // block comments
+    .replace(/--[^\n]*/g, ' ');          // line comments
+}
+
+const DOWN_MARKER = /(^|\n)[^\S\n]*(--+\s*)?(==+\s*)?DOWN\b/i;
+
+function hasDownSection(rawSql) {
+  return DOWN_MARKER.test(rawSql) || /\bMIGRATE\s+DOWN\b/i.test(rawSql);
+}
+
+// The UP section is what runs against live data; a DROP COLUMN there is
+// destructive. The DOWN section legitimately reverses an additive UP (e.g. an
+// ADD COLUMN's down IS a DROP COLUMN), so only the UP portion is scanned for
+// irreversible/risky statements.
+function upSection(rawSql) {
+  const m = DOWN_MARKER.exec(rawSql);
+  return m ? rawSql.slice(0, m.index) : rawSql;
+}
+
+export function analyze(rawSql) {
+  const code = stripComments(upSection(rawSql));
+  const errors = [];
+  const warnings = [];
+
+  for (const [re, msg] of IRREVERSIBLE) {
+    if (re.test(code)) errors.push(`irreversible: ${msg}`);
+  }
+  const irreversible = errors.length > 0;
+
+  // A down-migration is required UNLESS the change is irreversible (a faked
+  // "down" for an irreversible op is worse than none — see rollback-and-safety).
+  if (!irreversible && !hasDownSection(rawSql)) {
+    errors.push('missing down-migration: add a "-- DOWN" section or mark reversibility');
+  }
+
+  for (const [re, msg] of WARNINGS) {
+    if (re.test(code)) warnings.push(`risky: ${msg}`);
+  }
+
+  return { ok: errors.length === 0, errors, warnings, irreversible };
+}
+
+function report(label, sql) {
+  const { ok, errors, warnings } = analyze(sql);
+  if (ok) console.log(`✓ ${label}: no blocking issues`);
+  else {
+    console.error(`✗ ${label}:`);
+    errors.forEach((e) => console.error(`    - ${e}`));
+  }
+  warnings.forEach((w) => console.warn(`    ! ${label}: ${w}`));
+  return ok;
+}
+
+function selftest() {
+  const cases = {
+    pass_add_column_reversible: {
+      sql: '-- UP\nALTER TABLE t ADD COLUMN x int NULL;\n-- DOWN\nALTER TABLE t DROP COLUMN x;',
+      shouldPass: true,
+    },
+    pass_concurrent_index: {
+      sql: '-- UP\nCREATE INDEX CONCURRENTLY i ON t (x);\n-- DOWN\nDROP INDEX CONCURRENTLY i;',
+      shouldPass: true,
+    },
+    pass_drop_in_comment_only: {
+      // "DROP TABLE" appears ONLY inside a comment; real statements are additive
+      // with a valid down. Comment-stripping must prevent a false positive.
+      sql: '-- NOTE: this does NOT drop table t\n-- UP\nALTER TABLE t ADD COLUMN y int NULL;\n-- DOWN\nALTER TABLE t ALTER COLUMN y DROP DEFAULT;',
+      shouldPass: true,
+    },
+    fail_drop_table: {
+      sql: '-- UP\nDROP TABLE legacy;',
+      shouldPass: false,
+    },
+    fail_truncate: {
+      sql: '-- UP\nTRUNCATE audit_log;',
+      shouldPass: false,
+    },
+    fail_missing_down: {
+      sql: '-- UP\nALTER TABLE t ADD COLUMN z int NULL;',
+      shouldPass: false,
+    },
+  };
+
+  let allOk = true;
+  for (const [name, { sql, shouldPass }] of Object.entries(cases)) {
+    const { ok } = analyze(sql);
+    const correct = ok === shouldPass;
+    allOk = allOk && correct;
+    console.log(
+      `${correct ? '✓' : '✗'} selftest ${name}: ${ok ? 'pass' : 'fail'} ` +
+      `(expected ${shouldPass ? 'pass' : 'fail'})`
+    );
+  }
+  process.exit(allOk ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') {
+  selftest();
+} else if (arg) {
+  let sql;
+  try { sql = readFileSync(arg, 'utf8'); }
+  catch { console.error(`cannot read file: ${arg}`); process.exit(1); }
+  process.exit(report(arg, sql) ? 0 : 1);
+} else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(report('stdin', buf) ? 0 : 1));
+}