# 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.

*Canonical: https://makerkit.dev/docs/void-cloudflare/deployment/migrations*

---

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

```bash
# 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:

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

See [Adding Plugins](../authentication/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](./production#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](./production#what-a-deploy-does)).

## 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.

| 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](../cleanup/purge-targets)).

## Resetting Locally

```bash
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](./troubleshooting)).
- **A new `NOT NULL` column on a table with rows.** Add it nullable, backfill, then set `NOT NULL` in a later migration.
