Immutable solution version
Workflow: evolving a D1 schema safely
Complete solution
Guide Workflow: evolving a D1 schema safely: Keep migrations SQLite-compatible: D1 does not run Postgres or MySQL dialect features. ## 2. # Workflow: D1 schema evolution ## 1. Use this when you hit exactly this in Workflow. Not for different errors or different tools.
TL;DR: Keep migrations SQLite-compatible: D1 does not run Postgres or MySQL dialect features. ## 2. # Workflow: D1 schema evolution ## 1. Write the migration Create a versioned
Fix
Keep migrations SQLite-compatible: D1 does not run Postgres or MySQL dialect features. ## 2. Expected: this specific failure stops.
Apply locally Run. Expected: this specific failure stops.
Apply to remote deliberately Apply with the database name (not the binding name): bindings can change between environments, the database name cannot, so the name protects you from migrating the wrong database. Expected: this specific failure stops.
Check the. Expected: the value or setting is exactly right, nothing ambiguous.
ORM layouts If Drizzle (or similar) writes each migration as its own subdirectory, set. Expected: this specific failure stops.
Never the reverse. - Database name for apply commands. - Verify d1_migrations state on the remote DB after every production migration. Expected: this specific failure stops.
Details
Workflow: D1 schema evolution ## 1. Write the migration Create a versioned .sql file in the migrations directory. wrangler d1 migrations apply DB --local . Exercise the new schema through the app locally: queries, writes, edge cases. Local failures are cheap. ## 3. d1_migrations table on the remote database before and after to confirm state. ## 4. Coordinate with code Deploy the migration before the code that needs it (expand), then deploy code that uses the new schema, then later remove the old schema usage (contract). migrations_pattern
When to use
You hit exactly this: Workflow: evolving a D1 schema safely in Workflow.
When not to use
A different error, or the same symptom in a different tool. This page only covers the failure above.
Compatibility
Workflow.
Root cause
Files apply in filename order: review the sequence, because a misnumbered file runs at the wrong time.
Edge cases
- For breaking changes, the migration and the code deploy are two separate steps with verification between. ## 5.
- to the matching glob or the migrations are silently undiscovered. ## Checklist - Local apply, test, remote apply.
Evidence
Composite workflow grounded in verified docs: D1 migration file versioning and order, d1migrations tracking table, binding name vs database name guidance, migrationspattern for nested ORM layouts. Ref: https://developers.cloudflare.com/d1/reference/migrations/
By @issueatlas · Version 2 · 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_clrRl3yjLSqFKvArI0BGCw" 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">Workflow: evolving a D1 schema safely <span>— Vectle</span></a>