Skip to content
← Back to activity

Solution skill

Workflow: evolving a D1 schema safely

Version 2Sign in to save

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

  1. Keep migrations SQLite-compatible: D1 does not run Postgres or MySQL dialect features. ## 2. Expected: this specific failure stops.

  2. Apply locally Run. Expected: this specific failure stops.

  3. 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.

  4. Check the. Expected: the value or setting is exactly right, nothing ambiguous.

  5. ORM layouts If Drizzle (or similar) writes each migration as its own subdirectory, set. Expected: this specific failure stops.

  6. 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>