Database Operations

Runbook for migrations, seeding, backup and restore, and Postgres health in development and production.

Safety

bun db:push is useful for rapid development resets but should not be used as a production migration strategy.

Core Commands

bun db:migrate
bun db:generate
bun db:studio
bun db:seed
bun db:seed:plans
bun db:seed:users
bun db:seed:admins

bun db:push exists for rapid dev iteration but is destructive and dev-only.

Use bun db:generate and bun db:migrate for schema evolution.

Use bun db:seed for historical setup and bun db:seed:plans for pricing/bootstrap corrections.

Use bun db:studio and Postgres health probes to validate state before and after changes.

Migration Workflow

Generate migration artifacts when schema changes:

bun db:generate

Apply migrations:

bun db:migrate

Validate in Drizzle Studio:

bun db:studio

Seeding Notes

bun db:seed maps to historical seed data script.
Plan seeding can be run independently with bun db:seed:plans.
In deployment docs, plans are seeded after app startup in production bootstrap flows.

Local Health Checks

docker compose exec postgres pg_isready -U postgres
docker compose logs -f postgres

Or run:

bun health

Backup and Restore

# Backup
docker compose exec postgres pg_dump -U ai ai > backup-$(date +%Y%m%d).sql

# Restore
docker compose exec -T postgres psql -U ai ai < backup-20240108.sql

Adjust username/database to your actual POSTGRES_USER and POSTGRES_DB.

Production Caveats

Apply migrations after deploy before validating new features.
Keep DB credentials out of source-controlled files.
If app cannot connect in Compose, use service hostname (postgres) inside containers, not localhost.
Regular backups are part of the repository security and ops checklist.

Database Incident Checklist

Postgres container healthy and reachable
DATABASE_URL matches environment topology
Latest migrations applied
Seed dependencies present (for plans/billing flows)
Recent backup available before risky changes