db-migration

name	db-migration
description	Create and apply a Drizzle schema change. Use when adding or altering tables, columns, or indexes in @packages/db, or when asked for a migration.

Database Migration

PostgreSQL + Drizzle ORM. Schema in packages/db/src/schema/, migrations in packages/db/drizzle/. Schema, SQL, and snapshot travel together in one PR.

Workflow

1. Edit the schema

• New table: create packages/db/src/schema/<name>.ts, then export it from index.ts: export * from "@/schema/<name>". Every new table must be exported there or it never reaches a migration.
• Examples: auth.ts for tables, relations, and indexes; waitlist.ts for a minimal non-auth table.
• Conventions: text primary keys (.$defaultFn(() => crypto.randomUUID()) on non-auth tables), timestamp("created_at").defaultNow().notNull(), snake_case columns, onDelete: "cascade" on FKs, an index() on every FK column.

2. Generate and review

bun run db:generate

Read the generated packages/db/drizzle/NNNN_*.sql. Done when that SQL, its meta/NNNN_snapshot.json, and a new meta/_journal.json entry all appear and the SQL matches the schema edit.

3. Apply

bun run db:migrate

Local / ad-hoc only. The API build auto-applies pending migrations on production and canary deploys (.github/scripts/migrate-on-deploy.ts, gated on VERCEL_ENV/VERCEL_GIT_COMMIT_REF; PR previews skipped), so a migration merged to canary applies itself on the next deploy.

4. Make the running stack see it

bunx turbo run build --filter=@packages/db

The API consumes @packages/db's built dist. If dev is running and the API imports the new table, restart dev entirely: bun --hot does not pick up new files or exports reliably (see the dev skill).

5. Inspect data

bun run db:studio

Notes

• POSTGRES_URL comes from the root .env.
• Never edit an applied migration; generate a new one instead.