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.