Database and migrations

Setup and configuration

Configure DATABASE_URL for the intended Postgres database in the server environment. Use a separate disposable database for integration acceptance. Never aim test migrations at a production database.

The database workspace exports schema definitions and persistence helpers. Review packages/db/src/schema.ts and the migration directory before introducing a table or column.

pnpm --filter @starterkit/db db:generate
pnpm --filter @starterkit/db db:migrate

Implementation workflow

Generate a migration after editing the schema, inspect the generated SQL, and commit it with the schema change. Plan how existing records receive values before adding a required column.

Include workspaceId on every user-owned record and carry that scope into reads and writes. Use immutable model-price history for AI accounting instead of rewriting prices used by existing usage records.

Verification and troubleshooting

Apply migrations to an isolated database and run database-gated tests there. Missing credentials should produce an explicit skipped gate, not an assertion that persistence passed. If migration fails, inspect which statement failed and the current schema before retrying.