Shared PostgreSQL migrations
This skill covers shared PostgreSQL migrations only. It does not govern Durable Object SQLite or Wrangler migrations. Read packages/db/AGENTS.md first; it is canonical for shared PostgreSQL and Drizzle invariants. Use the git-rebase skill for migration conflicts during a rebase.
Workflow
- Read
packages/db/AGENTS.mdand inspect relevant schema and migration files. - Change
packages/db/src/schema.tsfirst. - Generate artifacts with
pnpm drizzle generate. - Inspect generated SQL.
- Review generated DDL for destructive operations and data loss. Prefer additive or staged schema changes. If generated DDL is unsafe, wrong, or too broad, correct the schema and regenerate. Do not hand-edit generated DDL, snapshots, or journal entries.
- Append only intentional
UPDATEorINSERTdata backfills after generated DDL, separated with--> statement-breakpoint. - Apply migrations with
pnpm drizzle migrateor runpnpm drizzle:verify-bootstrapwhen relevant. - Run
pnpm formatand targeted schema or migration checks. - Prefer one generated migration per unshipped feature branch. To squash migrations before shipping, remove the branch-local migration SQL, snapshots, and journal entries, then regenerate once from the current schema. Re-append intentional backfills afterward.
Keep generated artifacts generated. packages/db/AGENTS.md also covers shared-schema PII requirements and DB-backed timestamp serialization.