Database

Sora UI's documentation site keeps sign-in sessions and bookmarks in a Postgres database. The schema and client live in packages/db, built on Drizzle ORM and postgres.js.

Recommended: Neon

Neon is the provider we recommend for self-hosting Sora UI. It fits the way this app talks to Postgres:

• Pooled connections at runtime. Neon exposes a PgBouncer endpoint that accepts thousands of client connections over a small pool of real ones — ideal for a serverless deployment that opens a connection per request.
• Direct connections for migrations. The same project hands you a direct (unpooled) endpoint, which schema migrations need because transaction-mode pooling does not support session-level state.
• Branching for preview deployments. A Neon branch is an instant, copy-on-write clone of the database with its own connection string — handy for testing migrations without touching production.
• Scale to zero. Idle computes suspend after a few minutes, so a low-traffic docs site costs close to nothing.

Connection strings

Neon gives you two URLs for the same database. They differ only by the -pooler suffix in the hostname:

Both use port 5432 and require sslmode=require:

DATABASE_URL="postgresql://USER:PASSWORD@ep-xxx-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require"
DATABASE_URL_DIRECT="postgresql://USER:PASSWORD@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require"

Copy both URLs from the Neon console with the Connect button. Enable Connection pooling for DATABASE_URL, then disable it for DATABASE_URL_DIRECT.

The Neon CLI can pull the pooled and direct URLs as DATABASE_URL and DATABASE_URL_UNPOOLED:

neon env pull

This project uses DATABASE_URL_DIRECT instead of Neon's DATABASE_URL_UNPOOLED name, so copy the unpooled value into DATABASE_URL_DIRECT in apps/www/.env.

Environment variables

Set these in apps/www/.env:

Applying migrations

Schema lives in packages/db/src/schema. Run migrations from the package root:

cd packages/db
bun run db:migrate

drizzle-kit prefers DATABASE_URL_DIRECT and falls back to DATABASE_URL. Always give it a direct connection — running migrations through a transaction-mode pooler fails in confusing ways.

Other schema commands:

bun run db:generate   # generate SQL from the schema
bun run db:push       # push schema without a migration file (dev only)
bun run db:studio     # open Drizzle Studio

Using a different Postgres provider

Any Postgres provider works — the schema is plain Postgres, and the client connects with prepare: false so it stays compatible with transaction-mode poolers (Neon's -pooler endpoint, Supabase's port 6543).

Point DATABASE_URL at a pooled endpoint and DATABASE_URL_DIRECT at a direct one, then apply the migrations above.