PgCache 0.9.3

0.9.3 makes a TOML config file behave the same way wherever it is used: the Docker image no longer overrides parts of it, an unknown key is an error, and PgCache can write the file at its first start. It also serves LIMIT and OFFSET from the cache as node-postgres and PostgREST send them. The changelog lists every change.

Upgrading from 0.9.2

Both steps apply only if you run PgCache with a config file. A deployment configured through environment variables or CLI arguments alone needs no change.

An unknown key in the config file stops the start

0.9.2 ignored a key it did not know, so a misspelled setting was silently left at its default. 0.9.3 refuses to start and names the key and its line.

The usual cause is not a typo but TOML’s table rule: a key belongs to the last [table] header above it. A top-level setting appended to the end of the file lands in the last table, where it was ignored:

[listen]
socket = "0.0.0.0:5432"

excluded_tables = ["audit_logs"]   # read as listen.excluded_tables

The error says so when this is what happened (excluded_tables is a top-level key and must come before the first [table] header). Move the key above the first table header. Before upgrading, check the file for keys that are not in the TOML reference.

A mounted config file decides num_workers, [listen] and [cdc]

With CONFIG_FILE set, the 0.9.2 image still passed its own defaults for the worker count, the listen port and the publication and slot names, and those overrode the file. 0.9.3 passes only what you set, so the file’s values now take effect.

If your file sets any of these to something other than the image defaults, the running values change at the upgrade. The one to check is [cdc]: with different names in the file, PgCache creates and uses a new publication and slot. After the upgrade, confirm in pg_replication_slots that the slot 0.9.2 used is gone, since a slot nothing reads holds WAL on the origin. To keep what 0.9.2 ran with, either set the file to these values or set the variables:

SettingVariable0.9.2 always used
num_workersNUM_WORKERSabout one per allocated CPU, minimum 2
[listen] socketLISTEN_PORTport 5432
[cdc] publication_namePUBLICATIONpgcache_pub
[cdc] slot_nameSLOTpgcache_slot

See Docker → Mounting a TOML config for what still comes from the environment.

Config Files in Docker

Three things that failed with a mounted config file now work:

  • The file needs no [cache] table. The image runs the cache database and supplies the connection. A file written from the documented fields failed at start with “missing field cache”.
  • ORIGIN_PASSWORD applies to an origin named in the file. The image dropped the password when the file held the origin, so the password had to be written into the file. REPLICATION_PASSWORD works the same way.
  • The individual ORIGIN_* variables override the file. Port, user, database and TLS mode can differ per environment while the rest stays in the file.

Letting PgCache write the file

CONFIG_CREATE=1 was documented but never created a file. With CONFIG_FILE pointing at a path on a volume, the first start now writes a complete config file from the settings it was given, and later starts run from it:

services:
  pgcache:
    image: pgcache/pgcache
    volumes:
      - pgcache-config:/etc/pgcache
    environment:
      CONFIG_FILE: /etc/pgcache/config.toml
      CONFIG_CREATE: 1
      UPSTREAM_URL: postgres://user@db:5432/myapp
      ORIGIN_PASSWORD: ${ORIGIN_PASSWORD}

volumes:
  pgcache-config:

The file holds the required settings as resolved at that start, and an optional setting only when you set it, so a later release’s default still applies to the rest. It never holds a password, including one inside UPSTREAM_URL. An existing file is never overwritten. See Docker → Creating the config file.

Reload and restart_required

  • POST /config/reload keeps what a flag or environment variable set. A reload read the file alone, so a setting given outside it, such as ALLOWED_TABLES, was dropped at the first reload.
  • restart_required in GET /config is true only when a restart would change something. It was true from startup whenever a flag or environment variable overrode the file. It now compares the file, resolved under the startup flags, with what is running.

Also in This Release

  • excluded_tables names tables never to cache, the counterpart of allowed_tables. See How Caching Works.
  • FETCH FIRST n ROWS WITH TIES was cached as LIMIT n, so a cache hit left out the tied rows. It is now forwarded to the origin.
  • A bound LIMIT or OFFSET sent without a declared type failed every cache serve and fell back to the origin. It is now served from the cache, which is what lets paginated reads from node-postgres and PostgREST hit.