Database Migrations
Managing database schema changes and migrations using Drizzle ORM.
MuseMVP uses Drizzle Kit for schema migrations. Migrations are SQL files generated from schema changes and applied in order to keep your database in sync with the codebase.
Migration Workflow
Edit src/backend/database/schema.ts — add tables, columns, or indexes.
Run pnpm drizzle:generate — Drizzle generates a new migration file in src/backend/database/migrations/.
Review the generated SQL — ensure it matches your intent.
Run pnpm drizzle:migrate — apply migrations to your database.
Migration Files
The template currently ships a baseline migration plus later numbered diffs. Fresh databases should apply 0000_*.sql from zero, then 0001_*.sql (adds app_setting and app_setting_revision for Runtime Settings). After you change schema.ts in a running project, generate additional numbered files as usual.
- SQL files: Each migration is a numbered SQL file (e.g.
0000_*.sql, then0001_*.sqlfor later diffs). - Journal:
meta/_journal.jsontracks migration order and metadata.
Do Not Edit Applied Migrations
Once a migration has been applied to production, do not modify it. Create a new migration for further changes.
Commands Reference
| Command | Purpose |
|---|---|
pnpm drizzle:generate | Generate migration from schema diff |
pnpm drizzle:migrate | Apply pending migrations |
pnpm drizzle:push | Push schema directly (skips migrations; dev only) |
pnpm drizzle:studio | Open Drizzle Studio for visual DB inspection |
When to Use drizzle:push vs drizzle:migrate
| Approach | Use Case |
|---|---|
| drizzle:migrate | Production, team projects, version-controlled schema changes |
| drizzle:push | Local prototyping, quick schema iteration; no migration history |
For production deployments, always use drizzle:migrate and commit migration files.
Configuration
Migrations use the same connection as the app. Ensure DATABASE_URL (or Hyperdrive for Cloudflare) is set before running:
# .env
DATABASE_URL="postgresql://user:pass@host:5432/dbname"The Drizzle config in drizzle.config.ts reads from DATABASE_URL and outputs migrations to ./src/backend/database/migrations.