d1-migration-guard

mattbridges.github.io/d1-migration-guard

Three zero-dependency safety checks to run before wrangler d1 migrations apply. Free, MIT-licensed, reads local files only — never calls wrangler and never touches a live database.

What it does

1. Ordering (src/ordering.js) — sorts migration filenames explicitly and flags anything that would differ under raw filesystem order, plus duplicate or gapped numeric prefixes. This is the exact bug class fixed upstream in cloudflare/workers-sdk#13568.
2. Config validation (src/config.js) — parses wrangler.toml's [[d1_databases]] blocks (a narrow hand-rolled parser, not a general TOML library, to stay zero-dependency) and flags a missing or placeholder database_id — the failure mode behind workers-sdk#5049.
3. Destructive-SQL scan (src/destructive-sql.js) — regex-based flags for DROP TABLE, ALTER TABLE ... DROP COLUMN, unsafe renames, unfiltered DELETE FROM, and DROP INDEX. Deliberately a fast pattern scan, not a real SQL parser: false positives are fine (a human reviews the flag), false negatives on obfuscated SQL are a known, documented limitation of this v0.1 free tier.

Usage

Not yet published to npm (see Status below), so for now, clone and run directly:

git clone https://github.com/MattBridges/d1-migration-guard.git
cd d1-migration-guard
node bin/d1-migration-guard.js check --migrations-dir /path/to/migrations --config /path/to/wrangler.toml

Requires Node.js >= 18. Zero npm dependencies.

Exit code 2 on any high-severity finding, 0 otherwise (including "minor issues found" — a human still reads the output either way).

Status: v0.1, verified against a real Node runtime

Executed (not just self-reviewed) via node:20 against two fixture sets — a clean migration set (all three checks pass, exit 0) and a deliberately bad one (duplicate/gapped ordering, a placeholder database_id, and DROP TABLE/DROP COLUMN/unfiltered DELETE in one file). All three checks correctly detected every planted issue with the expected exit code (2). Source-only release for now — not yet published to the npm registry (the npx d1-migration-guard form in earlier drafts of this README doesn't work until that happens).

Not implemented yet (paid-tier scope)

• No actual dry-run against a local D1 copy (would shell out to wrangler d1 execute --local) — gated on this free CLI validating demand first.
• No cross-environment audit log or Slack/email alerting — planned as a $15-25/mo hosted tier if the free tier gets real signal (stars, issues, usage reports).

License

MIT