Configuration

SetupConfiguration.json, environment overrides, GUCs, and naming rules.

Two layers, one vocabulary:

Environment variables override the JSON file when set. Typical Docker installs ship a config that listens on 0.0.0.0:6379 and connects to Postgres as redis / redis / pg_resp.

Prefix rules

1. Product / RESP endpoint — PG_RESP_
   Settings that belong to the Redis-facing gateway (listen port, storage mode).
2. PostgreSQL backend — POSTGRESQL_
   Host, port, and database the gateway uses to reach Postgres.
3. Auth — unprefixed USERNAME / PASSWORD
   Postgres role the gateway uses for SQL. Redis AUTH verifies against the same roles. Wire auth is required by default; set REQUIRE_CLIENT_AUTH=false to allow unauthenticated clients. See Authentication.
4. Behavior flags — plain verbs, no product prefix when they are not product-specific: REQUIRE_POSTGRES, REQUIRE_CLIENT_AUTH, ALLOW_EXTERNAL_CONNECTIONS, ASYNC_RUNTIME_WORKER_THREADS.
5. Do not invent aliases. One name per setting.

Environment ↔ JSON map

Booleans accept 1 / true / yes (and 0 / false / no).

# Example: listen on 6380 and point at a non-default Postgres port
PG_RESP_PORT=6380 POSTGRESQL_PORT=5433

Example config file

{
  "GatewayListenPort": 6379,
  "UseLocalHost": false,
  "PostgresHostName": "127.0.0.1",
  "PostgresPort": 5432,
  "PostgresDatabase": "pg_resp",
  "PostgresSystemUser": "redis",
  "PostgresPassword": "redis",
  "RequirePostgres": true,
  "RequireClientAuth": true,
  "StorageMode": "unlogged",
  "AsyncRuntimeWorkerThreads": 2
}

Point Postgres at the file with:

shared_preload_libraries = 'pg_cron,pg_resp_gw_host,pg_prewarm'
pg_prewarm.autoprewarm = on
redis_gateway.database = 'pg_resp'
redis_gateway.setup_configuration_file = '/etc/pg_resp/SetupConfiguration.json'

GUCs

In-process host GUCs (require shared_preload_libraries including pg_resp_gw_host):

• redis_gateway.database
• redis_gateway.setup_configuration_file
• pg_resp.ttl_delete_batch_size (default 1000) — SQL TTL sweeper keys/round
• pg_resp.ttl_delete_max_rounds (default 10) — rounds per delete_expired_keys call

Tune the TTL pair with ALTER SYSTEM / postgresql.conf + pg_reload_conf(), or SET before a manual CALL pgresp.delete_expired_keys().

pg_cron

pg_cron is a Postgres extension that runs scheduled SQL. PostRESP uses it for active TTL expiry: job pg_resp_ttl_task calls pgresp.delete_expired_keys() once a minute.

Docker / compose preload pg_cron and set cron.database_name to the product database. Init creates the extension; CREATE EXTENSION pg_resp schedules the job when pg_cron is present.

Lazy expiry on read/write still works without pg_cron; without it, expired keys are only removed when touched. Batch size for the sweeper is controlled by the pg_resp.ttl_delete_* settings above — see Commands › TTL.

pg_prewarm

pg_prewarm ships with a standard PostgreSQL install. Docker / compose preload it and leave autoprewarm on by default (see Buffer cache prewarm):

Compose convenience (maps to the setting above; not a gateway JSON field):

Postgres server settings are a separate surface from gateway env/JSON — prefer the names in postgresql.conf. The compose variable above exists only so make postgres-up can toggle autoprewarm without editing the command array.

Memory and buffer cache

Keys live in Postgres heaps and indexes (pgresp.*), not in a dedicated in-process Redis dict. The full keyspace does not need to fit in RAM — only the hot working set should, via shared_buffers and the OS page cache. Cold keys stay on disk until read.

Disk vs Redis RAM. Tiny string keys are stored twice in spirit (registry row in keys + payload in strings) plus btree indexes, so on-disk bytes per key are typically higher than Redis/used_memory for the same logical shape. That is expected: you trade denser always-RAM encoding for SQL visibility and datasets larger than memory. Do not compare Redis INFO memory to Postgres process RSS — Postgres always carries shared buffers, catalogs, and backends.

Measure schema size when capacity-planning disk:

SELECT pg_size_pretty(SUM(pg_total_relation_size(c.oid))) AS pgresp_total
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE n.nspname = 'pgresp' AND c.relkind = 'r';

Container / image exceptions

These are not gateway config names; do not reuse them as new public APIs:

• POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB — official Postgres image init
• PGPORT — libpq default port inside the container (set from POSTGRESQL_PORT)
• PG_PREWARM_AUTOPREWARM — compose → pg_prewarm.autoprewarm only (see above)