Database Migrations

The workflow for changing the database schema: edit the schema, generate a migration, review and commit it, and let the deploy apply it.

You change the database by editing apps/web/db/schema.ts and generating a SQL migration from it. Migrations are committed files. The local database applies them with void db migrate, and production applies them during the deploy.

The Workflow

# 1. edit apps/web/db/schema.ts
# 2. write the migration from the change
pnpm --filter web exec void db generate
# 3. read the new file in apps/web/db/migrations/
# 4. apply it to your local database
pnpm --filter web exec void db migrate

Then commit the migration, its snapshot in db/migrations/meta/, and void.lock.json if it changed. A coding agent uses the kit_db_status and kit_db_migrate tools for the last step.

Always read the generated SQL before committing. Check that a rename wasn't written as a drop and an add, and that a new NOT NULL column has a default or a backfill.

Auth Tables

apps/web/db/auth-schema.ts is generated from the Better Auth options. Never edit it. After changing a plugin or an additionalFields entry, regenerate it first:

pnpm --filter web exec vp run auth:generate
pnpm --filter web exec void db generate

See Adding Plugins.

What Runs Where

WhereWhat applies migrations
Your machinepnpm --filter web exec void db migrate, against DATABASE_URL in apps/web/.env
GitHub checksNothing is applied to a real database. The check fails if the schema and the migrations disagree
ProductionThe deploy (vp run deploy), before the new version takes traffic

Production is any hosted PostgreSQL 17 or newer: PlanetScale (recommended), Neon or Supabase (Choosing a Database).

The deploy stops when schema.ts has a change without a migration. Don't point apps/web/.env at production to run migrations yourself: let the deploy do it (Production Deploys).

Safe Changes

Rollback never reverts a migration. After a rollback, the older code runs against the newer schema. So make every change in two deploys:

  1. Expand. Add the new column or table and keep the old one. Deploy code that works with both.
  2. Contract. Remove the old one in a later deploy, once no running version reads it.
ChangeHow
Add a columnNullable or with a default, in one deploy
Rename a columnAdd the new one, write to both, backfill, switch reads, then drop the old one later
Drop a column or tableStop reading and writing it first; drop it in the next deploy
Add a foreign keyIndex the column in the same migration

For tables that grow without bound (events, logs), don't add a foreign key with a cascade. Use an indexed owner column and a purge target (Purge Targets).

Resetting Locally

pnpm db:reset # drop everything and apply every migration again
pnpm db:seed # reset, then add the seed users

Use these rather than void db reset and void db seed. Void's own reset clears the public schema only, so the outbox's schema survives and the migrations fail when they run again. The kit's commands drop it first.

Rules

  • Never void db push except on a throwaway database. It changes the database without a migration, and the next deploy stops on drift.
  • Never edit a migration that has been deployed. Write a new one.
  • Never run SQL against production by hand to change the schema (void db execute --remote). The migration history would no longer match.
  • *_owner_guard.sql is hand-written. It keeps every organization from losing its last owner. Don't regenerate it or fold it into another migration.

Common Pitfalls

  • Schema drift at deploy. You changed schema.ts and didn't run void db generate. Generate, review, commit, push.
  • The check "Schema and migrations up to date" fails. Run auth:generate, then void db generate, and commit apps/web/db.
  • A migration fails in production. The deploy stops before a new version is uploaded, so the previous version keeps serving. Fix the migration, or add a new one, and deploy again (Troubleshooting).
  • A new NOT NULL column on a table with rows. Add it nullable, backfill, then set NOT NULL in a later migration.