Migrations

When to Use Migrations

Rule of thumb: Use db:push during development and early prototyping. Switch to db:generate + db:migrate once you have production data you can't afford to lose.

Migration Workflow

1. Edit the Schema

Make your changes in src/lib/db/schema.ts — add columns, tables, indexes, or modify types.

2. Generate a Migration

pnpm db:generate

Drizzle compares the schema against the last known state and generates a SQL migration file in src/lib/db/migrations/. Review the generated SQL before applying.

3. Apply the Migration

pnpm db:migrate

This runs all pending migrations against the database specified in TURSO_DATABASE_URL.

CI Migration Job

The .github/workflows/ci.yml includes an optional DB Migrate job that runs migrations on push to main.

To enable it:

1. Set the ENABLE_DB_MIGRATE repository variable to true in GitHub Settings → Variables
2. Add these repository secrets:
   • TURSO_DATABASE_URL — your production Turso URL
   • TURSO_AUTH_TOKEN — your production auth token

Optionally, set TURSO_DEMO_DATABASE_URL and TURSO_DEMO_AUTH_TOKEN to also migrate a demo database.

Rollback Strategy

Drizzle does not generate automatic rollback migrations. For safe rollbacks:

1. Before applying: Review the generated SQL in src/lib/db/migrations/
2. If something goes wrong: Write a new migration that reverts the change (e.g. drop the added column)
3. Consider backups: Use Turso's point-in-time recovery or create a database branch before applying risky migrations

Schema Conflicts During Upgrades

When upgrading Codapult, schema changes from the upstream may conflict with your own modifications:

1. Merge the upstream schema.ts changes with your local changes
2. Run pnpm db:generate to create a migration from the combined state
3. Review and apply with pnpm db:migrate

See the Upgrading guide for detailed conflict resolution steps.

Seed Workflow

A GitHub Actions workflow at .github/workflows/seed.yml lets you push schema and seed a database remotely:

gh workflow run seed.yml -f target=production -f seed_type=full

Targets: production or demo. Seed types: full (sample data) or demo (single admin account).