Storage

Persistence backends for the control plane: file system, PostgreSQL, and FoundationDB.

The control plane is stateful. Pick a backend by how many control plane nodes you run.

Multi-node deployments also need a pub/sub backend so nodes can coordinate. See Pub/sub below.

File system

RocksDB on the local disk. It is local to one node and cannot be shared, so it is the right choice for exactly one control plane instance and the wrong choice for two.

{
  "file_system": {
    "path": "/var/lib/rivet/data"
  }
}

RIVET__FILE_SYSTEM__PATH="/var/lib/rivet/data"

With no path set, the engine uses a platform default:

In a container or as a service the path defaults to ./data/db, relative to the working directory. Always mount a volume at whatever path you choose.

PostgreSQL

The recommended backend for multi-node deployments. It is production-ready for light-to-moderate workloads, up to roughly 1,000 concurrent actors. Past that, or for high-throughput realtime workloads, contact enterprise support about FoundationDB.

{
  "postgres": {
    "url": "postgresql://user:password@host:5432/database"
  }
}

RIVET__POSTGRES__URL="postgresql://user:password@host:5432/database"

Do not use a connection pooler

The engine needs direct connections for session-level features. PgBouncer, Supavisor, and AWS RDS Proxy are not supported. Where a managed provider offers both, use the direct connection string, not the pooled one.

TLS

Add sslmode to the connection URL:

require encrypts the connection but does not verify the server certificate. To verify against a CA, or to authenticate with a client certificate, set the paths explicitly:

{
  "postgres": {
    "url": "postgresql://user:password@host:5432/database?sslmode=require",
    "ssl": {
      "root_cert_path": "/path/to/root-ca.crt",
      "client_cert_path": "/path/to/client.crt",
      "client_key_path": "/path/to/client.key"
    }
  }
}

RIVET__POSTGRES__URL="postgresql://user:password@host:5432/database?sslmode=require"
RIVET__POSTGRES__SSL__ROOT_CERT_PATH="/path/to/root-ca.crt"
RIVET__POSTGRES__SSL__CLIENT_CERT_PATH="/path/to/client.crt"
RIVET__POSTGRES__SSL__CLIENT_KEY_PATH="/path/to/client.key"

All three are optional. Without them the engine uses the system root certificates.

Managed provider notes

RIVET__POSTGRES__URL="postgresql://pscale_api_<username>.<unique-id>:<password>@<region>.pg.psdb.cloud:5432/postgres?sslmode=require"

RIVET__POSTGRES__URL="postgresql://postgres:<password>@db.<project-ref>.supabase.co:5432/postgres?sslmode=disable"

RIVET__POSTGRES__URL="postgresql://postgres:<password>@db.<project-ref>.supabase.co:5432/postgres?sslmode=require"
RIVET__POSTGRES__SSL__ROOT_CERT_PATH="/path/to/supabase-ca.crt"

FoundationDB

A distributed, ordered key-value store originally built by Apple, and the backend behind iCloud, Snowflake’s metadata layer, Datadog, and Tigris. Its strict serializability, fault tolerance, and linear scaling make it the right fit for large deployments.

FoundationDB requires an enterprise license. Cluster setup is handled during onboarding. Contact enterprise support to get started.

Pub/sub (NATS)

Multi-node deployments use NATS to coordinate realtime messaging between control plane nodes. Single-node deployments need no pub/sub configuration at all.

{
  "postgres": {
    "url": "postgresql://user:password@host:5432/database"
  },
  "nats": {
    "addresses": ["nats:4222"]
  }
}

Run at least two NATS replicas for high availability.

Next steps

• Configuration reference
• Backups
• Production checklist