Database Migrations

Approach

D1 migrations are managed as numbered SQL files in db/migrations/. The canonical schema is maintained in db/schema.sql.

Creating a Migration

Use the /db-migrate Claude Code command:

/db-migrate

Or manually:

1. Create db/migrations/NNNN_description.sql with the SQL changes
2. Apply locally: wrangler d1 execute dotcollective-tools-db --local --file=db/migrations/NNNN_description.sql
3. Update db/schema.sql to reflect the current state
4. Test locally
5. Apply to production before deploy: wrangler d1 execute dotcollective-tools-db --remote --file=db/migrations/NNNN_description.sql

Best Practices

• Use CREATE TABLE IF NOT EXISTS and CREATE INDEX IF NOT EXISTS for idempotent schema
• Use INSERT OR REPLACE for seed data that may already exist
• Always update db/schema.sql to match the current state after migrations
• Test migrations locally before applying to production
• Back up production data before destructive migrations (D1 supports point-in-time recovery)