Release a D1 database: migrations, local verification, and Time Travel
Separate local and remote D1 state, release compatible schema migrations, and reserve Time Travel for human-approved recovery.
Edited and verified by Orange Book Editorial Team ·
Remote and local D1 are separate states
wrangler dev uses local data by default. A command with --remote touches a remote database and cannot be undone by closing the terminal. This guide defines a release gate; it does not execute a remote migration or restore for you.
Release principles
Traceable migration
d1_migrations records applied versions.Forward-compatible app
Confirmed recovery
A safe release line
Create a migration against a stable database name
pnpm exec wrangler d1 migrations create APP_DB add_document_statusPrefer a stable D1 database name for production operations rather than a binding that can be reused across environments. Review the SQL file. Do not mix irreversible data cleanup and an application switch into one migration.
Apply to the local database first
pnpm exec wrangler d1 migrations list APP_DB --local
pnpm exec wrangler d1 migrations apply APP_DB --localRun schema and read/write tests against an empty database and existing data. Confirm that a second list shows no pending work and that a failed migration does not leave a shape the application cannot interpret.
Build a forward-compatible release order
Deploy code that reads the old shape and optionally understands the new one, apply an additive remote schema after approval, then enable new writes and backfill. Put column deletion, rename, or large rewrites in a separate change window. Human-review AI-generated SQL for indexes, defaults, NULL behavior, and tenant predicates.
Add a human gate before remote execution
pnpm exec wrangler d1 migrations list APP_DB --remoteConfirm the account, database name, environment, pending files, backup/recovery owner, maintenance window, and rollback version. Run remote migrations apply only after approval. A tutorial or AI must not cross that gate automatically.
Verify business behavior, not only exit code
Check schema version, critical reads and writes, tenant isolation, indexed queries, error rate, and slow queries. Canary application code. On database errors, stop new-version traffic and write amplification before deciding between a forward fix and recovery.
Time Travel is not an ordinary undo
Time Travel is automatically available for remote D1 without additional cost, but a restore overwrites the database's current state. Retention also depends on the plan: the current limits page lists seven days for Free and 30 days for Paid. Verify the account and latest official limit before acting.
pnpm exec wrangler d1 time-travel info APP_DB \
--timestamp '2026-08-27T02:30:00Z'This command reads remote D1 information. Convert local event time to explicit UTC/RFC3339, then ask a second reviewer to confirm event time, database, and bookmark.
A restore discards state after the restore point
Time Travel is database-level disaster recovery, not the right undo for one user's mistaken operation. Prefer an audit trail and compensating write for a row or tenant-level error instead of rewinding every user.
Release and recovery checklist
- Empty and existing-data local upgrades pass.
- Application code works before and after the migration schema.
- Two reviewers confirm the remote database name, account, environment, and migration list.
- Write isolation, restore point, post-restore data handling, and traffic rollback have owners.
- Production verification covers reads, writes, tenant isolation, errors, and critical queries—not only CLI success.
For selection context, read D1 compared with Supabase and Neon. For the broader gate, see production launch checks.
Primary sources
Did this page help you complete your goal?
Beta feedback is generated in this browser and is never uploaded automatically.