A single ALTER TABLE statement took down one of my Workers mid-deploy. No maintenance window, no graceful fallback — just a wall of 500s while live traffic hit a broken schema.
D1 is SQLite under the hood, and SQLite's ALTER TABLE is one of the most restricted in any relational database. You can add a column. That's essentially it. No dropping columns, no type changes, no renames — not without a full table rebuild. Cloudflare's docs mention this, but they don't quite convey how fast it bites you in production. The specific error that woke me up:
Error: D1_ERROR: Cannot add a NOT NULL column with no default value [ code: 1 ]
I'd tried to add campaign_id TEXT NOT NULL to a live table. SQLite refused immediately — existing rows would violate the constraint the moment the column appeared. The migration halted, the Worker's code expected the column to exist, and every request that touched that table failed. The fix is obvious in hindsight: always pair NOT NULL with a DEFAULT value on any new column, or accept nullable first and tighten the constraint later. What's less obvious is when the DEFAULT approach isn't good enough — specifically, when an empty string or zero is semantically wrong for your data model. That's where the expand-contract pattern comes in: create a new table with the schema you actually want, copy the data across, drop the old table, rename. It's four SQL statements and it's the only safe path for type changes or true column drops in D1.
I've now run this flow on 3 live D1 databases since early 2025. The discipline that actually saves you is boring: apply to local first (wrangler d1 migrations apply --local), verify with PRAGMA table_info(...) after every migration, and keep migrations in numbered flat files with no fancy tooling between you and the SQL. Five wrangler commands cover every scenario I've hit.
I wrote up the full breakdown — including the complete expand-contract SQL, the exact wrangler commands I run for each step, and how to verify column state before touching production — over on dailymanuallab.com.