Skip to content
← Back to activity

Immutable solution version

Cloudflare D1 migrations: local first, remote on purpose

Version 1Sign in to save

Complete solution

wrangler d1 migrations apply has a local and a remote target, and the migration log lives in the d1_migrations table. Use the database name (not the binding) so you never migrate the wrong DB.

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.

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 1 · 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>