Start with what the application sees. The connection string points at port 5432, PgCache answers the Postgres wire protocol, and the client cannot tell it is not talking to the database [1][8]. Behind that, the proxy holds a second connection open as a replication consumer. When the write-ahead log shows that rows behind a cached result changed, the result is refreshed instead of aged out [2][3].
That is the actual trade, and it is a trade rather than a win. A materialized view makes you pick a refresh interval and serve slightly stale numbers between refreshes; a Redis layer makes you write and maintain the code that knows which keys to drop on every write [18]. Replication-driven invalidation removes both, and puts freshness on how fast the proxy drains WAL, which is not a number you configure [23].
The database-side setup is two things: `wal_level = logical` and replication permission on the login role [9]. The author reports he started with a hand-written `pg_hba.conf` rule and a `CREATE PUBLICATION` line, then deleted both after checking that PgCache creates its own publication and slot at startup, scoped to just the four tables it caches, which he confirmed in `pg_publication` [10]. A tool that narrows its own publication to the tables it will actually serve is doing the polite thing rather than asking for the whole cluster. The replication connection authenticates with the ordinary password [11]. The one hard stop is memory: the cache lives in `/dev/shm`, and startup fails unless that mount is more than twice the proxy's internal `shared_buffers`, with the required size printed in the error [12]. A sizing requirement that tells you the number it wants is better than most.
Now the numbers, which are claims about someone else's workload. The harness runs four queries 150 times each at concurrency 10 against both targets after warming both, which is 1,200 statement executions in total [13][20]. Every one of the 150 proxy runs registered as a hit on PgCache's own counter [14]. Three of the four shapes improved and one did not [21]: the aggregates fall from hundreds or thousands of milliseconds to under one, roughly two to three orders of magnitude, while the already sub-millisecond point lookup just pays for an extra process hop [16][22][15].
For those to transfer, your read mix has to look like that harness: the same query text repeating often enough to stay resident, result sets that fit in shared memory, and a write rate low enough that refresh is not continuous. The data was seeded to about 16 million rows precisely so the slow queries would appear on demand, so cardinality and distribution are the author's choices [5][6]. To his credit, indexes went on every foreign key and every filtered or grouped column first, so the comparison is against a tuned Postgres [7].
The feature worth reading the docs on is predicate subsumption: a cached `WHERE country = 'US'` also answers `WHERE country = 'US' AND tier = 'pro'` [17]. That is query rewriting inside the proxy, not key lookup, and it means the correctness surface now includes the subsumption logic. The write-visibility test is the one that decides whether any of this is safe, and the copy of the post supplied to us stops as it begins [24][25].
