Drizzle ORM database migration workflow. Use when making schema changes, adding columns/tables, or modifying the database. Triggers include "add a column", "create a table", "schema change", "migration", "db change", or any task that modifies drizzle schema files.
When making database schema changes, you MUST follow this exact process. Never write migration SQL or snapshot JSON by hand.
Make your changes in the drizzle schema source (e.g. apps/os/backend/db/schema.ts or similar schema.ts).
From the package directory (e.g. apps/os/):
pnpm drizzle-kit generate --name descriptive_migration_name
This produces three things:
.sql migration filemeta/_journal.jsonmeta/*_snapshot.jsonIf drizzle-kit asks interactive questions (e.g. "is this column created or renamed?"), answer them.
.sql fileYou MAY edit the generated .sql file — for example to add data migrations, backfills, or custom SQL that drizzle-kit can't auto-generate.
NEVER manually edit _journal.json or *_snapshot.json files. These are managed exclusively by drizzle-kit.
pnpm drizzle-kit check
Fix any reported issues before proceeding.
pnpm drizzle-kit migrate
Confirm the schema matches what your code expects.
.sql migration files from scratch — always generate them_journal.json or *_snapshot.json — these are drizzle-kit managedgenerate step — even if you "know" the SQLAfter merging schema changes, run:
PSCALE_DATABASE_URL=$(doppler secrets --config prd get --plain PLANETSCALE_PROD_POSTGRES_URL) pnpm os db:migrate
See docs/fixing-drizzle-migration-conflicts.md for detailed steps. The short version:
git checkout main -- <migrations-dir>/meta/.sql filespnpm drizzle-kit generate --name your_migrationpnpm drizzle-kit check