PostgreSQL

Configure PostgreSQL for self-hosted Rivet deployments.

Choosing a Backend

Pick your database backend based on how many engine nodes you run:

• Single-node: Use the file system backend (RocksDB). It is the recommended production-ready backend for single-node deployments. RocksDB is local to one node and cannot be shared across engine instances, and no pub/sub is needed.
• Multi-node: Use PostgreSQL as the database and NATS for pub/sub. PostgreSQL can be shared across engine nodes and is production-ready for light-to-moderate workloads, up to roughly 1,000 concurrent actors.
• Enterprise scale: Beyond that, or for high-throughput realtime workloads, PostgreSQL is not the right fit. Contact enterprise support about FoundationDB.

Basic Configuration

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

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

The configuration above is a complete single-node deployment and needs no pub/sub configuration, though for most single-node deployments the file system backend (RocksDB) is the recommended choice. For multi-node deployments, add NATS as the pub/sub backend so engine nodes can coordinate (see below).

Pub/Sub (NATS)

Rivet uses a pub/sub backend for realtime messaging between engine nodes. Single-node deployments do not need any pub/sub configuration.

Multi-node PostgreSQL deployments require NATS as the pub/sub backend so engine nodes can coordinate. Deploy 2+ NATS replicas for high availability.

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

See the production checklist and Configuration for details.

Managed Postgres Compatibility

Some hosted PostgreSQL platforms require additional configuration due to platform-specific restrictions.

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

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

{
  "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=disable"

{
  "postgres": {
    "url": "postgresql://postgres:<password>@db.<project-ref>.supabase.co:5432/postgres?sslmode=require",
    "ssl": {
      "root_cert_path": "/path/to/supabase-ca.crt"
    }
  }
}

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"

SSL/TLS Support

To enable SSL for Postgres, add sslmode=require to your PostgreSQL connection URL:

{
  "postgres": {
    "url": "postgresql://user:password@host.example.com:5432/database?sslmode=require"
  }
}

RIVET__postgres__url="postgresql://user:password@host.example.com:5432/database?sslmode=require"

The sslmode parameter controls TLS usage:

• disable: Do not use TLS
• prefer: Use TLS if available, otherwise connect without TLS (default)
• require: Require TLS connection (fails if TLS is not available)

To verify the server certificate against a CA or verify the hostname, use custom SSL certificates (see below).

Custom SSL Certificates

For databases using custom certificate authorities (e.g., Supabase) or requiring client certificate authentication, you can specify certificate paths in the configuration:

{
  "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 SSL paths are optional. If not specified, Rivet uses the default system root certificates from Mozilla’s root certificate store.

Do Not Use Connection Poolers

Rivet requires direct PostgreSQL connections for session-level features and does not support connection poolers.

Do not use:

• PgBouncer
• Supavisor
• AWS RDS Proxy