PostgreSQL
OpenDash keeps all of its state in one PostgreSQL. What version and extensions it needs, which connection goes where, and notes for Neon, Supabase, Amazon RDS and ClickHouse Managed Postgres.
PostgreSQL is OpenDash's only stateful dependency: application data, sign-in, the job queue (pg-boss), search (full text, trigram and vectors) and change notifications all live in it. The bundled compose file runs one for you; for anything larger, use a managed Postgres.
Requirements
- PostgreSQL 16, 17 or 18.
- The extensions
vector(pgvector 0.7 or later),pg_trgmandbtree_gin. The bootstrap names any your server doesn't ship, and migrations refuse a database without them. - Point-in-time recovery and daily backups for anything you care about.
Connection URLs
OpenDash uses three main connections, because a transaction pooler can't do everything:
| Variable | Mode | Used for |
|---|---|---|
DATABASE_URL | Transaction pooler is fine | App queries. Each sets its tenant for one transaction. With Supavisor, add prepare: false. |
DATABASE_DIRECT_URL | Direct or session mode | LISTEN, one connection per web or worker process, so answers stream as they're written. |
DATABASE_QUEUE_URL | Direct or session mode, as opendash_queue | The job queue, on its own pool. Workers run jobs; the web app only enqueues. |
Two more connect as their own roles: DATABASE_AUTH_URL (opendash_auth) and DATABASE_SYSTEM_URL (opendash_system). The bundled compose file sets all five for you.
No LISTEN? Streams still work
Without a LISTEN-capable URL, the web app falls back to polling for new events every 500 ms. It works, but answers feel less live.
Roles
Setup creates five roles, and OpenDash never needs BYPASSRLS (which managed providers often won't grant):
| Role | Purpose |
|---|---|
opendash_owner | Runs migrations only. |
opendash_app | The application. Has no BYPASSRLS, so row-level security always applies. |
opendash_auth | Sign-in and sessions. It can reach only the auth schema. |
opendash_queue | Owns the job queue schema. |
opendash_system | The routine dispatcher and maintenance. |
Managed providers
Neon
Use the non-pooler endpoint for DATABASE_DIRECT_URL: the -pooler host is PgBouncer in transaction mode and has no LISTEN. In production, turn autosuspend off: a suspended compute drops LISTEN sessions.
Supabase
Supavisor's transaction mode (port 6543) supports neither LISTEN nor prepared statements. Use session mode (5432) or a direct connection. Direct connections are IPv6 unless you buy the IPv4 add-on.
Amazon RDS and other private CAs
When the server's certificate comes from the provider's own certificate authority, add sslmode=verify-full to every URL and give both images the CA: as PEM text in OPENDASH_EXTRA_CA_CERTS (for platforms without file mounts, such as Railway), or as a mounted file named by NODE_EXTRA_CA_CERTS. With sslmode=require the connection is encrypted, but the server's identity isn't checked.
ClickHouse Managed Postgres
Port 5432 is direct (use it for setup, DATABASE_DIRECT_URL and DATABASE_QUEUE_URL); 6432 is PgBouncer in transaction mode (DATABASE_URL may use it). Create the opendash database first; the provider's superuser runs the bootstrap. It also signs with its own CA, so follow the section above.
Migrations
Migrations run in the one-shot setup service, under an advisory lock, before web and worker start. The web image never migrates. Migrations are forward-only and written to work while the previous version is still running, so rolling deploys are safe, except where the release notes say otherwise (see Upgrades). Long backfills run as background jobs.