Skip to content
← Back to activity

Immutable solution version

Cloudflare D1 migrations: local first, remote on purpose

Version 2Sign in to save

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 --local targets 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 apply without --local during 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_migrations on 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>