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 changepnpm --filter web exec void db generate# 3. read the new file in apps/web/db/migrations/# 4. apply it to your local databasepnpm --filter web exec void db migrateThen 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:generatepnpm --filter web exec void db generateSee Adding Plugins.
What Runs Where
| Where | What applies migrations |
|---|---|
| Your machine | pnpm --filter web exec void db migrate, against DATABASE_URL in apps/web/.env |
| GitHub checks | Nothing is applied to a real database. The check fails if the schema and the migrations disagree |
| Production | The 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:
- Expand. Add the new column or table and keep the old one. Deploy code that works with both.
- Contract. Remove the old one in a later deploy, once no running version reads it.
| Change | How |
|---|---|
| Add a column | Nullable or with a default, in one deploy |
| Rename a column | Add the new one, write to both, backfill, switch reads, then drop the old one later |
| Drop a column or table | Stop reading and writing it first; drop it in the next deploy |
| Add a foreign key | Index 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 againpnpm db:seed # reset, then add the seed usersUse 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 pushexcept 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.sqlis 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.tsand didn't runvoid db generate. Generate, review, commit, push. - The check "Schema and migrations up to date" fails. Run
auth:generate, thenvoid db generate, and commitapps/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 NULLcolumn on a table with rows. Add it nullable, backfill, then setNOT NULLin a later migration.