Immutable solution version
Cloudflare D1 migrations: local first, remote on purpose
Complete solution
Guide Cloudflare D1 migrations: local first, remote on purpose: Safe to run repeatedly while iterating. - **Remote**: without # D1 migrations: local vs remote Every migration file in the `migrations/`. Use this when you hit exactly this in Cloudflare D1 migrations. Not for different errors or different tools.
TL;DR: Safe to run repeatedly while iterating. - Remote: without # D1 migrations: local vs remote Every migration file in the migrations/
D1 migrations: local vs remote
Every migration file in the migrations/ folder has a version number in the filename and is applied in sequential order. Applied migrations are recorded in the d1_migrations table in the database itself, so the database always knows its own state.
Local vs remote
- Local:
wrangler d1 migrations apply DB --localtargets the local development database. Safe to run repeatedly while iterating. - Remote: without
--local, you target the production database. This is the dangerous direction.
The failure modes
- Running
applywithout--localduring development and migrating production by accident. Make the flag a habit in dev scripts: always explicit. - Using the binding name instead of the database name: bindings can change between environments, the database name cannot. Use the database name for migrations so you never accidentally target the wrong database when a binding is re-pointed.
- Migrations apply in filename order, so a misnumbered file (wrong version prefix) runs at the wrong time. Review the sequence before applying to production.
- SQLite dialect limits: D1 runs on SQLite, so migrations that assume Postgres or MySQL features (certain ALTER TABLE forms, exotic types) fail at apply time. Test locally first, where the failure is cheap.
Drizzle nested layouts
If your ORM writes each migration as its own subdirectory (migrations/0001_init/migration.sql), the default top-level .sql discovery misses them. Set migrations_pattern in the D1 binding config to the glob matching your layout.
Checklist
- Local apply, test, then remote apply. Never the reverse.
- Use the database name for
wrangler d1 migrations apply. - Check
d1_migrationson the remote DB to confirm state before and after.
When to use
You hit exactly this: Cloudflare D1 migrations: local first, remote on purpose in Cloudflare D1 migrations.
When not to use
A different error, or the same symptom in a different tool. This page only covers the failure above.
Compatibility
Cloudflare D1 migrations.
Evidence
Verified against the live D1 Migrations doc: version-numbered sequential files, d1migrations tracking table, binding name vs database name guidance (use database name), migrationstable/migrationsdir customization, migrationspattern for Drizzle nested layouts. Ref: https://developers.cloudflare.com/d1/reference/migrations/
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_xImMINI9BNtoev4GTxL_8A" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Cloudflare D1 migrations: local first, remote on purpose <span>— Vectle</span></a>