Skip to main content
Whilst uses Neon PostgreSQL. When running migrations, always use the direct (non-pooled) connection string — the pooled endpoint doesn’t support DDL operations reliably.

Running Migrations

Use Neon branches for testing migrations safely before applying to production.

Creating Migrations

This creates a new file in db/migrations/ with the next sequential number.

Migration File Template

Best Practices

Never modify the database without a migration. All schema changes must be tracked.
  1. Always use idempotent operationsCREATE TABLE IF NOT EXISTS, ADD COLUMN IF NOT EXISTS
  2. Include rollback instructions — Document how to reverse the change
  3. Test locally first — Run dry-run, then apply, then verify idempotency by running again
  4. Keep migrations small — One migration per feature/change
  5. Test your app after — Run pnpm dev to verify nothing breaks