Database

VibeAny uses PostgreSQL with Drizzle ORM. The same schema and committed SQL migrations support the included local database and hosted PostgreSQL providers.

Connect PostgreSQL

Set a standard PostgreSQL connection URL in .env.local:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/vibeany

The setup wizard accepts URLs beginning with postgresql:// or postgres:// and verifies the connection before writing the selected value.

For local development, start PostgreSQL 16 with:

docker compose up -d db

If port 5432 is already occupied, use a different host port through the wizard:

VIBEANY_POSTGRES_PORT=55432 npm run setup

You can also use Neon, Supabase PostgreSQL, or another compatible hosted service. Use the direct or pooled URL recommended by that provider and include its required TLS parameters.

Migration-only policy

Never run db:push or drizzle-kit push in local, preview, test, or production environments.

The db:push npm script intentionally exits with an error. Schema changes must be represented by reviewed migration files so every environment applies the same history.

Apply the delivered schema

The buyer archive already contains the committed migrations required for its version:

npm run db:migrate

The migration runner:

reads .env.local during ordinary local execution
creates an app_migrations tracker when needed
applies drizzle/*.sql files in lexical order
skips files already recorded as applied
executes each migration and its tracker record in the same database transaction
stops at the first failure

It is safe to rerun npm run db:migrate; successfully recorded files are not applied twice.

Change the schema

The schema source is src/lib/db/schema.ts. Use this workflow for every change:

# 1. Edit src/lib/db/schema.ts

# 2. Generate a migration in drizzle/
npm run db:generate

# 3. Review the generated SQL before execution

# 4. Apply it to the intended development database
npm run db:migrate

# 5. Inspect data and structure when useful
npm run db:studio

Commit the schema edit, generated SQL, and Drizzle metadata together. Never edit the production schema manually as a substitute for a migration.

Existing data domains

The delivered schema includes storage for:

Better Auth users, sessions, accounts, and verification tokens
provider-neutral subscriptions and checkout attempts
one-time orders and credit packages
credit balances and FIFO transaction history
idempotent webhook inbox records
uploaded-file metadata
MCP API keys, OAuth clients, grants, consent, and token state

Provider-neutral billing rows record the provider alongside the external ID. This preserves the origin of an existing subscription even when the configured provider for new checkout traffic later changes.

Review migrations before production

Generated SQL is a starting point, not an automatic approval. Check for:

destructive column or table changes
nullable-to-required transitions on existing data
indexes or constraints that existing rows may violate
long-running rewrites or locks
the required data backfill order
rollback or recovery steps

Back up important data according to your database provider's procedures before a risky migration. Test the exact committed migration against representative data before production.

Validate the production target

Before deployment, configure the intended production DATABASE_URL and run:

npm run preflight
npm run db:migrate

Preflight verifies connectivity and known migration-safety constraints. The supported deployment flow runs preflight before applying committed migrations.

Continue with Authentication and email, which uses the same PostgreSQL database for Better Auth state.