Database
The Reference Implementation uses a PostgreSQL database to store all of its data — tenants, users, service registrations, credentials metadata, configuration, and more. See System Architecture for what the database contains and how it relates to the external services.
Provisioning
When using the Docker Compose configuration from the repository, a PostgreSQL instance (ri-db) is provisioned automatically. Organisations using the Reference Implementation Docker image directly will need to provision their own PostgreSQL instance (version 17 or later recommended).
Configuration
The database connection can be configured either as a single connection string or as separate parts.
| Variable | Required | Description | Default |
|---|---|---|---|
RI_DATABASE_URL | No | A complete PostgreSQL connection string. Takes precedence over the RI_POSTGRES_* variables below when set. | — |
RI_POSTGRES_HOST | Yes, if RI_DATABASE_URL is not set | Database hostname | — |
RI_POSTGRES_PORT | No | Database port | 5432 |
RI_POSTGRES_USER | No | Database user | postgres |
RI_POSTGRES_PASSWORD | No | Database password | postgres |
RI_POSTGRES_DB | No | Database name | ri |
Set RI_DATABASE_URL directly when the connection string carries options the RI_POSTGRES_* parts cannot express, or when a secrets manager already supplies one. When it is set, the Reference Implementation uses it as given and does not construct a URL from the other variables.
The user and password defaults are the container entrypoint's fallbacks for quick local starts. Set explicit credentials in any real deployment, and see Minimum Privileges for the account to provision.
Minimum Privileges
Superuser access is not required. The migrations Prisma Migrate applies at startup perform standard DDL (creating, altering, and dropping the application's own tables, indexes, constraints, and enum types) plus data migrations on those tables, and never install PostgreSQL extensions.
On a shared PostgreSQL instance, provision a dedicated user that owns a dedicated database:
CREATE USER ri_user WITH PASSWORD '...';
CREATE DATABASE ri OWNER ri_user;
The Reference Implementation creates its tables in the database's default public schema; the connection URLs its tooling constructs always target public.
On a freshly created PostgreSQL 15+ database this is sufficient for the container's startup path (prisma migrate deploy) and for the application at runtime: the database owner is an implicit member of pg_database_owner, which owns the public schema, so USAGE and CREATE follow without further grants. On a database that was restored from a dump or upgraded from an earlier PostgreSQL major version, the public schema keeps its previous owner and permissions, so check that ri_user can create in it and that untrusted roles cannot.
The Docker Compose configuration in the repository provisions a dedicated ri-db container whose init user (ri-postgres by default) is that container's cluster superuser, which is the standard behaviour of the official PostgreSQL image for a single-purpose instance. That does not mean the application needs superuser rights; when pointing the Reference Implementation at a shared instance, the dedicated owner-user above is sufficient.
Migrations and Seeding
On startup, the Reference Implementation automatically applies database migrations and seeds system default records. See Startup for the full sequence, what gets seeded, and how to control each step.
Local Development
For local development, the Prisma CLI provides useful tools:
cd packages/reference-implementation
# Visual database editor
pnpm prisma studio
# Create and apply a new migration
pnpm prisma migrate dev