drizzle-migrations

Drizzle Migrations

Overview

Complete migration lifecycle for the ToStudy monorepo: schema change, generation, review, apply, troubleshoot, and production recovery. Migrations live in packages/database/migrations/ and are tracked by a three-part system (SQL files + journal + DB table).

When to Use

digraph {
  "What do you need?" [shape=diamond];
  "Schema change?" [shape=diamond];
  "Migration error?" [shape=diamond];
  "Production issue?" [shape=diamond];

  "What do you need?" -> "Schema change?" [label="add/alter table"];
  "What do you need?" -> "Migration error?" [label="error on migrate"];
  "What do you need?" -> "Production issue?" [label="Railway deploy fail"];

  "Schema change?" -> "Schema → Generate → Review → Apply" [label="yes"];
  "Migration error?" -> "Diagnose Desync" [label="yes"];
  "Production issue?" -> "Production Recovery" [label="yes"];
}

Quick Reference

Action	Command
Generate migration	pnpm db:generate
Apply migrations	pnpm db:migrate
Push schema (dev only)	pnpm db:push
Open Drizzle Studio	pnpm db:studio
Validate state	pnpm db:validate
Regenerate sync SQL	pnpm db:sync-hashes
Run seed	pnpm db:seed
Extended seed	pnpm db:seed:extended
Dev seed	pnpm db:seed:dev

Migration Workflow

Step 1: Edit Schema

All schema files in packages/database/src/schema/. Edit the relevant file or create a new one.

New table checklist:

• UUID primary key with defaultRandom()
• createdAt / updatedAt timestamps with timezone
• Foreign keys with explicit onDelete behavior
• Indexes on FK columns and frequent WHERE/ORDER BY columns
• Export table + relations + inferred types from schema/index.ts

Step 2: Generate Migration

pnpm db:generate

This creates a new SQL file in packages/database/migrations/ and updates migrations/meta/_journal.json.

CRITICAL: Rename the file if Drizzle generated a random name (e.g., 0201_jittery_shadowcat.sql):