With Wrangler 4 and Cloudflare D1, how do wrangler d1 migrations create and apply work, and how do changes reach local and remote databases?
answer
- numbered SQL files in a folder
- a table remembers what ran
- local unless told otherwise
- deploy ships code, not schema
basics
~20 swrangler d1 migrations create writes a numbered .sql file into migrations/. wrangler d1 migrations apply runs every file not yet recorded in the database's d1_migrations table: on the local database by default, and on the real one only with --remote.
solid answer
~40 s`wrangler d1 migrations create <database> <message>` writes the next numbered file, such as `migrations/0001_create_notes.sql`, for you to fill with SQL. `wrangler d1 migrations apply <database>` compares the folder with the `d1_migrations` table in the target database and runs each unapplied file in order, recording its name in the same execution; if a file fails, that migration is rolled back and earlier ones stay applied. In Wrangler 4 the commands target the local database under `.wrangler/state` unless you pass `--remote`; `--env` selects an environment's binding and `--remote --preview` its `preview_database_id`. `wrangler deploy` never applies migrations, so a release runs `apply --remote` as its own step, normally before deploying code that needs the new schema. An applied file is never edited: its name is already recorded, so the change would never run there.
code
bash · 5 linesnpx wrangler d1 migrations create notes-db "add note tags"
npx wrangler d1 migrations apply notes-db --local
npx wrangler d1 migrations list notes-db --remote
npx wrangler d1 migrations apply notes-db --remote
npx wrangler deploygo deeper
Recall the create and apply commands, the numbered files in migrations/, and that --remote is what changes the real database.
Explain the d1_migrations table, how apply picks unapplied files, the per-file rollback, the local default in Wrangler 4 and where local data lives.
Show you can order a release: remote migrations before an additive deploy, renames split across releases, --env for each environment, and why applied files stay untouched.
Decide who may run remote migrations, whether the pipeline or a person applies them, and how schema changes are reviewed before they reach production.
## Migration files and the migrations table A **migration** is a versioned `.sql` file that moves the schema one step forward. D1's migration tooling lives in Wrangler: 1. `wrangler d1 migrations create <database> <message>` writes the next numbered file into the migrations folder, `migrations/` by default. The first one in a project is `0001_<message>.sql`, with spaces in the message turned into underscores; the next is `0002_...`. The new file holds only a comment, for you to replace with SQL. 2. `wrangler d1 migrations list <database>` shows the files not yet applied. 3. `wrangler d1 migrations apply <database>` applies them. `<database>` can be the database name or the binding name. The documentation suggests the name, because a binding name in the config can change while a database name cannot. `apply` first makes sure a tracking table exists in the target database, `d1_migrations` by default, with `id`, `name` and `applied_at` columns. It reads the names already recorded there, compares them with the files on disk and runs each unapplied file in numeric order. Each file's SQL runs together with the `INSERT` that records its name, and if anything in the file fails, that migration is rolled back while the earlier ones stay applied. Per binding, `migrations_table` and `migrations_dir` rename the table and the folder, and `migrations_pattern`, added in 2026, is a glob for nested layouts such as one folder per migration. Migrations are not the only way to run SQL from Wrangler. `wrangler d1 execute <database> --command "<SQL>"` or `--file <path>` runs SQL once and records nothing in `d1_migrations`. That suits seed data, a one-off data fix or a quick inspection query, but schema history written that way cannot be replayed on a new database, so schema changes belong in migration files. With `--remote --file`, Wrangler warns that the database will be unavailable to serve queries while the file is processed. ## Local first, remote on request Every Wrangler D1 command that touches data picks a target: | Flags | Target | |---|---| | none | The local database (the default since Wrangler 3.33) | | `--local` | The same local database, stated explicitly | | `--remote` | The real D1 database in the Cloudflare account | | `--remote --preview` | The database named by `preview_database_id` | | `--local --persist-to <dir>` | A local database kept under another directory | The local database is a SQLite file that Wrangler keeps under `.wrangler/state/v3/d1` in the project, the same store `wrangler dev` reads by default. Applying to it is how a developer gets new tables into the database their local Worker sees, and it changes nothing in production. Add `--env <name>` to use a Wrangler environment's own `d1_databases` entry: bindings are not inherited between environments, so each environment names its own database and needs its own `apply`. ## Shipping a schema change `wrangler deploy` uploads code; it never applies D1 migrations. A release therefore has two steps that the pipeline must order: 1. Apply the migrations with `wrangler d1 migrations apply <database> --remote`. In CI or another non-interactive shell the confirmation prompt is skipped. 2. Deploy the Worker that uses the new schema. Applying first is safe when the change is **additive**, such as a new table or a column with a default, because the Worker that is still running keeps working against the new schema. A rename or drop that running code still reads has to be split across releases: add the new shape, deploy code that uses it, and remove the old shape in a later migration. Wrangler also warns that the database may not be available to serve requests while migrations run, so a large data rewrite belongs in small steps. ## Rules that keep migrations trustworthy - **Never edit an applied file.** Its name is already recorded in `d1_migrations`, so the edit never runs where the file was applied, while new databases get the edited version and the schemas drift apart. Write a new migration instead. - **Commit the folder with the code**, so every environment applies the same sequence. - **Use `PRAGMA defer_foreign_keys = true`** in a migration that must briefly violate a foreign key, for example while rebuilding a table. D1 enforces foreign keys by default and checks deferred ones at the end of the transaction. - **Keep schema changes out of request handlers.** Running `CREATE INDEX` or another schema change on the request path repeats the work, and building an index is billed as row writes each time. - **Read the target before confirming.** Wrangler prints whether it is executing on the local or the remote database; checking that line prevents an unintended production change.
- After wrangler deploy, every request fails with D1_ERROR: no such table: notes: SQLITE_ERROR, though wrangler dev worked. What happened?The migrations were applied only to the local database, the default target, so `wrangler dev` saw the tables and production never got them; `wrangler deploy` does not run migrations. Run `wrangler d1 migrations list notes-db --remote` to see what is pending, apply with `--remote` (plus `--env` for that environment), and make it a pipeline step before deploy.
- How do you try a migration before it reaches production?Apply it to the local database with `wrangler d1 migrations apply <database> --local` and exercise the Worker under `wrangler dev`. For a remote copy, set `preview_database_id` and apply with `--remote --preview`. The Workers test harness can also apply the same folder to each test file's database, which the material on the runtime test harness covers.
- Why pass the database name rather than the binding name to migrations apply?Both are accepted, but a binding name is a label in the Wrangler file that can be renamed or pointed at another database, while a database name is fixed when the database is created. Using the name avoids applying a migration to the wrong database after a config change.
- wrangler deploy applies any pending D1 migrations automatically.
- With no flag, migrations apply runs against the production database.
- Editing an already-applied migration file updates every database on the next apply.
- A failed migration file leaves its earlier statements applied.
- Applying migrations with --local also updates the remote database.
Assumes Wrangler 4 (4.149.0): the D1 migration commands have targeted the local database by default since Wrangler 3.33, and migrations_pattern for nested layouts was added in 2026.