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
| Method | Usage | Best For |
|---|---|---|
| Environment variables | UPSTREAM_URL=postgres://... | Docker deployments (recommended) |
| CLI arguments | Passed via Docker command | Overriding specific values |
| TOML file | Mounted into container | Version-controlled config |
TOML Configuration Reference
[origin] — Origin Database Connection
The PostgreSQL database that PgCache caches queries for.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
host | string | yes | — | Origin database hostname |
port | integer | yes | — | Origin database port |
user | string | yes | — | Database user |
password | string | no | — | Database password |
database | string | yes | — | Database name |
ssl_mode | string | no | disable | TLS mode: disable, require, or verify-full |
[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.
| Field | Type | Default | Description |
|---|---|---|---|
host | string | origin host | Replication host |
port | integer | origin port | Replication port |
user | string | origin user | Replication user |
password | string | origin password | Replication password |
database | string | origin database | Replication database |
ssl_mode | string | origin ssl_mode | TLS mode: disable, require, or verify-full |
[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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
publication_name | string | yes | — | Name of the publication PgCache creates on the origin |
slot_name | string | yes | — | Name of the logical replication slot PgCache creates on the origin |
[listen] — Proxy Listener
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
socket | string | yes | — | Address and port to listen on (e.g., 0.0.0.0:5432) |
[metrics] — Prometheus Metrics (Optional)
In the Docker image the metrics socket is always 0.0.0.0:METRICS_PORT (default 9090), which the image’s health check probes; this table applies when you run the binary yourself.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
socket | string | yes | — | Address and port for the metrics HTTP endpoint. A wildcard address (0.0.0.0 or [::]) binds dual-stack where the host supports it, so localhost resolves over IPv4 or IPv6; the proxy listener binds its address as given |
[cache] — Cache Database Connection (Self-Managed Only)
PgCache keeps cached rows in a PostgreSQL database of its own, the cache database. This table tells PgCache where that PostgreSQL is.
You do not set it with the Docker image or the AWS Marketplace AMI. Both run the cache PostgreSQL themselves and point PgCache at it, so leave [cache] out of a config file you mount into the image; the image overrides it if it is there. Set it only when you run the pgcache binary yourself against a PostgreSQL you provide.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
host | string | yes | — | Cache PostgreSQL hostname |
port | integer | yes | — | Cache PostgreSQL port |
user | string | yes | — | Role PgCache connects as |
database | string | yes | — | Name of the cache database |
The same four values can be given as --cache_host, --cache_port, --cache_user and --cache_database; with all four flags the table can be omitted.
What the cache PostgreSQL has to provide:
- A database PgCache may destroy. At every start PgCache connects to the
postgresdatabase on that server, ends the sessions on the cache database, drops it and creates it again. Never name a database that holds anything else. - A dedicated instance, next to PgCache. Every cache hit is a query against it, so run it on the same host. PgCache connects without a password and without TLS: allow
trustauthentication for this role from PgCache’s address inpg_hba.conf, and do not expose the instance beyond that. - A role that can do the reset. It drops and creates the database, ends other sessions on it and creates extensions; in practice a superuser of that instance.
- The
pgcache_pgrxextension, installed and preloaded (shared_preload_libraries = 'pgcache_pgrx'), andpg_stat_statementsinstalled. PgCache creates both in the cache database at each start. Seepgcache_pgrxfor build and install steps. - Origin’s locales and sort order. The cache database is created under origin’s encoding and collation, and PgCache refuses to start when the two servers order text differently. See Compatibility → Known Limitations.
Top-Level Settings
General
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
num_workers | integer | yes | — | Number of worker threads for handling connections. Also sets the bounds of the cache serve pool, which sizes itself between num_workers × 2 and num_workers × 8 connections |
population_workers_min | integer | no | max(num_workers, 2) | Floor and starting size of the population worker pool. Each worker holds one origin and one cache connection |
population_workers_max | integer | no | num_workers × 8 | Ceiling on the population worker pool — the maximum number of concurrent population queries against the origin. The pool grows toward it only while population queue wait is high and added workers raise throughput. A value below the default floor also lowers the floor |
role_poll_interval | integer | no | 5 | Seconds between polls of the origin’s role catalog for role membership and attribute changes, which the schema-change signal cannot report. A change forgets every cached privilege verdict, so it takes effect within one interval. 0 disables the poll |
log_level | string | no | — | Log level filter. Supports simple levels ("info", "debug") and module-specific filters ("pgcache_lib::cache=debug,info") |
telemetry | boolean | no | true | Anonymous telemetry reporting. Set to false to disable. See Telemetry for details on what is collected |
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.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
cache_size | integer | no | — | Deprecated and ignored. Superseded by disk_limit; setting it logs a deprecation warning and has no effect |
cache_policy | string | no | clock | Eviction policy: clock (second-chance) or fifo (oldest first) |
admission_threshold | integer | no | 1 | Number of times a query must be seen before cache admission (clock policy only; 1 admits on first occurrence) |
mv_size_ratio | integer | no | 10 | Materialized result size gate (row-reduction test). A shape-eligible query (aggregate, GROUP BY, DISTINCT, etc.) passes this gate when result_rows × mv_size_ratio ≤ source_rows at first population — i.e. the result is at least this many times smaller than the input. A query is materialized if it passes either this gate or mv_compute_min_rows. Window functions materialize unconditionally |
mv_compute_min_rows | integer | no | 1000 | Materialized-view compute-avoidance gate. A shape-eligible query passes this gate when its population source-row count is at least this value — so large inputs aren’t recomputed from source rows on every serve, regardless of how much the result reduces them. A query is materialized if it passes either this gate or mv_size_ratio |
memo_cache_size | integer | no | ¼ of memory, min 64 MiB | Total byte budget for the in-process result memo, an in-memory tier that serves the hottest queries inline without a cache-database round-trip. Defaults to a quarter of the memory available to PgCache (the container’s limit, or host RAM), and at least 64 MiB; 0 disables it |
memory_limit | integer | no | — | Absolute ceiling (bytes) on pgcache’s total memory footprint (the pgcache process plus the cache Postgres it manages). When unset, the ceiling is 80% of detected RAM (cgroup-aware in containers: the tightest limit on the cgroup ancestor chain applies, and usage is measured as the working set, excluding reclaimable page cache). As whole-system used memory approaches the ceiling, registration of new distinct queries is throttled — they are forwarded to origin instead of cached — bounding memory under high query cardinality. A configured value can only lower the effective ceiling, never raise it above 80% of RAM |
disk_limit | integer | no | — | Cap (bytes) on space used on the cache volume — the disk analogue of memory_limit. When the volume’s used space exceeds it, registration of new queries is throttled and cache tables are dropped to reclaim space. When unset, the limit auto-derives from the cache volume’s live free space, keeping a reserve free |
allowed_tables | array | no | — | Only cache queries referencing these tables. Supports unqualified ("orders") and schema-qualified ("audit.orders") names. If omitted, all tables are cacheable |
excluded_tables | array | no | — | Never cache queries referencing these tables; they are forwarded to the origin. Same name forms as allowed_tables, and wins over it. See Excluded Tables |
Pinned Queries
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
pinned_queries | array | no | — | SQL queries to pin in cache at startup. Pinned queries are pre-populated, protected from eviction, and auto-readmitted after CDC invalidation |
pinned_tables | array | no | — | Tables to pin in cache. Each table is expanded to SELECT * FROM {table} and merged with pinned_queries |
TLS
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
tls_cert | string | no | — | Path to TLS certificate (PEM) for client connections |
tls_key | string | no | — | Path to TLS private key (PEM) for client connections |
Full Example Configuration
num_workers = 4
# disk_limit = 10737418240 # max cache-volume bytes used; unset auto-derives from free space
# 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: never cache these tables
# excluded_tables = ["audit_logs", "analytics.events"]
# 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"
# No [cache] table: the Docker image and the AMI supply the cache database.
# Running the binary yourself? See the [cache] section above.
[listen]
socket = "0.0.0.0:5432"
[metrics]
socket = "0.0.0.0:9090"CLI Arguments Reference
These are the flags of the pgcache binary; a flag overrides the config file’s value. The Docker image takes its own dash-separated options (--upstream, --workers, …) and the environment variables listed below; run docker run --rm pgcache/pgcache --help for both.
| Flag | Description |
|---|---|
-c, --config | Path to TOML configuration file |
--config_create | When the config file is missing, write it from the flags given and start from it. Required settings are always written, optional ones only when a flag set them; passwords and the cache database connection are left out |
--origin_host | Origin database host |
--origin_port | Origin database port |
--origin_user | Origin database user |
--origin_password | Origin database password |
--origin_database | Origin database name |
--origin_ssl_mode | Origin TLS mode (disable, require, or verify-full) |
--replication_host | Replication host override |
--replication_port | Replication port override |
--replication_user | Replication user override |
--replication_password | Replication password override |
--replication_database | Replication database override |
--replication_ssl_mode | Replication TLS mode override |
--cache_host, --cache_port, --cache_user, --cache_database | Cache database connection, for a PostgreSQL you run yourself; the Docker image and the AMI set these. See [cache] |
--cdc_publication_name | Logical replication publication name |
--cdc_slot_name | Logical replication slot name |
--listen_socket | Listen address and port |
--num_workers | Number of worker threads |
--population_workers_min | Population worker pool floor (default max(num_workers, 2)) |
--population_workers_max | Population worker pool ceiling (default num_workers × 8) |
--role_poll_interval | Seconds between role catalog polls (default 5; 0 disables) |
--cache_size | Deprecated and ignored; use --disk_limit |
--cache_policy | Eviction policy (clock or fifo) |
--admission_threshold | Query admission threshold (clock policy only) |
--mv_size_ratio | Materialized result size gate (default 10) |
--mv_compute_min_rows | Materialized-view compute-avoidance gate — also materializes any input of at least this many source rows (default 1000) |
--memo_cache_size | In-process result memo byte budget (default a quarter of memory, at least 64 MiB; 0 disables) |
--memory_limit | Absolute RSS ceiling in bytes for registration throttling (default: 80% of RAM; can only lower) |
--disk_limit | Cap (bytes) on cache-volume space used before throttling + table drops (default: auto from free disk) |
--tls_cert | TLS certificate file path |
--tls_key | TLS private key file path |
--metrics_socket | Prometheus metrics listen address |
--log_level | Log level filter |
--allowed_tables | Comma-separated list of tables to cache |
--excluded_tables | Comma-separated list of tables never to cache |
--pinned_queries | Semicolon-separated queries to pin in cache |
--pinned_tables | Comma-separated tables to pin in cache |
--telemetry_off | Disable anonymous telemetry reporting |
--check | Check that the origin is ready for PgCache, print a report and exit. Exit status 1 when a check fails. |
--cleanup | Drop this instance’s replication slot and publication on the origin and exit; with --purge, also the shared event triggers and schema. See Operations |
--healthcheck | Probe a running PgCache’s /healthz on --metrics_socket and exit 0 when it answers |
--version | Print the PgCache version and exit |
Docker Environment Variables
When running the PgCache Docker image, these environment variables are available. They map to the entrypoint’s CLI options.
With a mounted config file (CONFIG_FILE), a variable you set overrides the file and one you leave unset defers to it: the defaults below for LISTEN_PORT, NUM_WORKERS, PUBLICATION, SLOT and the ORIGIN_* fields apply only without a config file. METRICS_PORT always applies. See Mounting a TOML config.
The origin database can be given either as a single UPSTREAM_URL or as individual ORIGIN_* fields; when both are set, the individual fields override the URL. The same applies to the replication connection (REPLICATION_URL vs the REPLICATION_* fields). Individual fields avoid URL-encoding credentials that contain special characters.
| Variable | Description | Default |
|---|---|---|
UPSTREAM_URL | Origin database URL (postgres://user:pass@host:port/db) | — (required unless ORIGIN_HOST or CONFIG_FILE set) |
ORIGIN_HOST | Origin host (alternative to UPSTREAM_URL; overrides the URL) | — |
ORIGIN_PORT | Origin port | 5432 |
ORIGIN_USER | Origin user | postgres |
ORIGIN_PASSWORD | Origin password | — |
ORIGIN_DATABASE | Origin database | — |
ORIGIN_SSL_MODE | Origin TLS mode (disable, require, verify-full) | disable |
CONFIG_FILE | Path to TOML config file (mounted into container) | — |
CONFIG_CREATE | Set to 1/true to write CONFIG_FILE from the settings given when nothing is at that path yet. See Creating the config file | — |
REPLICATION_URL | Replication connection URL (defaults to upstream) | — |
REPLICATION_HOST | Override replication host | — |
REPLICATION_PORT | Override replication port | — |
REPLICATION_USER | Override replication user | — |
REPLICATION_DATABASE | Override replication database | — |
REPLICATION_PASSWORD | Override replication password | — |
REPLICATION_SSL_MODE | Override replication TLS mode | — |
LISTEN_PORT | Proxy listen port | 5432 |
METRICS_PORT | Prometheus metrics port | 9090 |
CACHE_PG_FLAVOUR | Embedded cache PostgreSQL: auto, native (the image’s own) or al2 (collates like RDS and Aurora) | auto |
NUM_WORKERS | Number of worker threads | auto (≈1 per allocated CPU, min 2) |
PUBLICATION | Publication name | pgcache_pub |
SLOT | Replication slot name | pgcache_slot |
CDC_SUFFIX | Suffix appended to publication and slot names | — |
CACHE_SIZE | Deprecated and ignored. Superseded by DISK_LIMIT | — |
DISK_LIMIT | Cap (bytes) on cache-volume space used before disk-pressure reclaim engages | auto from free disk |
CACHE_POLICY | Cache eviction policy: clock or fifo | clock |
ADMISSION_THRESHOLD | Number of times a query must be seen before caching | 1 |
MV_SIZE_RATIO | Materialized result size gate (row-reduction test): a shape-eligible query passes when result_rows × MV_SIZE_RATIO ≤ source_rows | 10 |
MV_COMPUTE_MIN_ROWS | Materialized-view compute-avoidance gate: a shape-eligible query is also materialized when its source-row count reaches this value | 1000 |
MEMO_CACHE_SIZE | In-process result memo byte budget (0 disables) | ¼ of memory, min 64 MiB |
MEMORY_LIMIT | Absolute RSS ceiling in bytes for registration throttling (can only lower) | 80% of RAM |
ALLOWED_TABLES | Comma-separated list of tables to cache (default: all) | — |
EXCLUDED_TABLES | Comma-separated list of tables never to cache (default: none) | — |
PINNED_QUERIES | Semicolon-separated queries to pin in cache | — |
PINNED_TABLES | Comma-separated tables to pin in cache | — |
LOG_LEVEL | Log level filter (e.g., debug, info, pgcache_lib::cache=debug) | — |
PGCACHE_POPULATION_WORKERS_MIN | Population worker pool floor (read directly by the binary) | max(NUM_WORKERS, 2) |
PGCACHE_POPULATION_WORKERS_MAX | Population worker pool ceiling (read directly by the binary) | NUM_WORKERS × 8 |
PGCACHE_ROLE_POLL_INTERVAL | Seconds between role catalog polls (read directly by the binary); 0 disables | 5 |
PGCACHE_TELEMETRY | Set to off to disable anonymous telemetry reporting | — |
PGCACHE_TLS_CERT | Base64-encoded TLS certificate | — |
PGCACHE_TLS_KEY | Base64-encoded TLS private key | — |
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 individual origin fields (avoids URL-encoding credentials with special characters):
docker run -d -p 5432:5432 \
-e ORIGIN_HOST=db.example.com \
-e ORIGIN_DATABASE=myapp \
-e ORIGIN_USER=app_user \
-e ORIGIN_PASSWORD='p@ss/w:rd' \
-e ORIGIN_SSL_MODE=require \
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"