wrangler d1: Cloudflare D1 Migrations in CI
wrangler d1 provisions and queries Cloudflare D1 databases and applies SQL migrations from the command line.
D1 is Cloudflare's SQLite database for Workers. In CI you typically run migrations against the remote database after deploy.
What it does
wrangler d1 create makes a database and prints its id for wrangler.toml. wrangler d1 execute runs SQL (from --command or --file) against a database. wrangler d1 migrations apply runs pending files from the migrations directory. --remote targets the live database; --local hits the dev SQLite file.
Common usage
wrangler d1 create app-db
# run a one-off statement against the remote database
wrangler d1 execute app-db --remote --command "SELECT count(*) FROM users;"
# apply pending migrations to the remote database
wrangler d1 migrations apply app-db --remoteOptions
| Command / flag | What it does |
|---|---|
| create <name> | Create a D1 database, print its id |
| execute <db> | Run SQL against the database |
| --command <sql> / --file <f> | Inline SQL or a .sql file |
| migrations apply <db> | Apply pending migration files |
| --remote | Target the live database (not the local file) |
| --local | Target the local dev SQLite database |
In CI
Pass --remote explicitly in pipelines; without it d1 commands hit a local SQLite file that does not exist on a fresh runner, so migrations appear to do nothing on production. The CLOUDFLARE_API_TOKEN needs the D1 edit permission.
Common errors in CI
"Authentication error [code: 10000]" means a missing or under-scoped token. "Couldn't find a D1 DB with the name or binding" means the database_id in wrangler.toml is wrong or the binding is missing. Migrations that "did nothing" usually ran against --local instead of --remote.