Configuration

PgCache supports three configuration methods: a TOML config file, CLI arguments, and Docker environment variables. These can be combined — CLI arguments override TOML file values, and Docker environment variables are mapped to CLI arguments by the container entrypoint.

Configuration Methods

TOML Configuration Reference

[origin] — Origin Database Connection

The PostgreSQL database that PgCache caches queries for.

[replication] — Replication Connection (Optional)

Override connection settings for CDC logical replication. Every field is optional and cascades from [origin] when not specified. This is useful when your application connects through a connection pooler like PgBouncer, but CDC replication needs a direct connection to PostgreSQL.

[cdc] — Change Data Capture

Settings for PostgreSQL logical replication. PgCache creates and manages the publication and replication slot automatically on the origin database using these names.

[listen] — Proxy Listener

[metrics] — Prometheus Metrics (Optional)

Top-Level Settings

General

Cache Behavior

The fields in this section plus log_level can be changed at runtime via the HTTP admin API (PUT /config) without restarting. See Monitoring for the admin endpoints.

Pinned Queries

TLS

Full Example Configuration

num_workers = 4
# cache_size = 1073741824      # deprecated; disk limit auto-derives from free space when unset
# cache_policy = "clock"       # or "fifo"
# admission_threshold = 1      # clock policy only
log_level = "info"

# Optional: restrict caching to specific tables
# allowed_tables = ["users", "orders", "products"]

# Optional: pin queries in cache at startup
# pinned_queries = [
#     "SELECT * FROM settings",
#     "SELECT * FROM categories",
# ]

# Optional: pin entire tables (shorthand for pinned_queries)
# pinned_tables = ["settings", "categories"]

[origin]
host = "db.example.com"
port = 5432
user = "app_user"
password = "secret"
database = "myapp"
ssl_mode = "require"

# Optional: override replication connection
# Useful when origin is behind PgBouncer
[replication]
host = "db-direct.example.com"
port = 5432

[cdc]
publication_name = "pgcache_pub"
slot_name = "pgcache_slot"

[listen]
socket = "0.0.0.0:6432"

[metrics]
socket = "0.0.0.0:9090"

CLI Arguments Reference

All TOML fields can be set via command-line arguments. CLI values override TOML values.

Docker Environment Variables

When running the PgCache Docker image, these environment variables are available. They map to the entrypoint’s CLI options.

Docker Examples

Basic:

docker run -d -p 5432:5432 pgcache/pgcache \
  --upstream postgres://user@db:5432/myapp

With replication override (origin behind PgBouncer):

docker run -d -p 5432:5432 pgcache/pgcache \
  --upstream postgres://user@pgbouncer:6432/myapp \
  --replication-host db-direct.example.com \
  --replication-port 5432

With environment variables:

docker run -d -p 5432:5432 \
  -e UPSTREAM_URL=postgres://user@db:5432/myapp \
  -e NUM_WORKERS=8 \
  -e REPLICATION_HOST=db-direct.example.com \
  pgcache/pgcache

With a mounted TOML config file:

docker run -d -p 5432:5432 -p 9090:9090 \
  -v ./pgcache.toml:/etc/pgcache/config.toml:ro \
  -e CONFIG_FILE=/etc/pgcache/config.toml \
  pgcache/pgcache

With table allowlist and pinned tables:

docker run -d -p 5432:5432 \
  -e UPSTREAM_URL=postgres://user@db:5432/myapp \
  -e ALLOWED_TABLES=users,orders,products \
  -e PINNED_TABLES=users,products \
  pgcache/pgcache

With pinned queries:

docker run -d -p 5432:5432 pgcache/pgcache \
  --upstream postgres://user@db:5432/myapp \
  --pinned-queries "SELECT * FROM config;SELECT * FROM lookup"