--- layout: default title: "PostgreSQL row cache extension | pg_local_cache" seo_title: "PostgreSQL Row Cache Extension | pg_local_cache" description: Cache PostgreSQL primary-key rows in shared memory with explicit SQL mget and transaction-aware invalidation. Try the local demo and compare it with batched SQL. image: /assets/social-card.png last_modified_at: "2026-09-14" home: true permalink: / ---

A row cache
inside PostgreSQL.

Read rows by primary key with one SQL call. PostgreSQL writes automatically invalidate affected cache entries.

Try locally Compare with SQL

Explicit SQL API · PostgreSQL 14–18 · Open source

One call. Two read paths.

An eligible hit returns the stored row. A miss or bypass reads the source table. Your ordinary SELECT queries keep their existing path.

psql │ primary-key reads
-- Attach your table once.
SELECT local_cache.attach_table('public.items');

-- Read rows by primary key.
SELECT local_cache.mget(
  'public.items', ARRAY[42, 7]::bigint[]
);

Node.js exampleGo exampleRESP example

{% include diagrams/read-path.html id="home-read" %}
What a row-cache hit avoids
SQL mget

Up to 1,024 keys per call. Order, duplicates, and NULL positions are preserved.

Ordinary writes

INSERT, UPDATE, and DELETE invalidate affected entries.

Fixed capacity

Allocate the shared row cache at PostgreSQL startup.

Snapshot checks

Ineligible reads use the source table under PostgreSQL visibility rules.

Measured on Apple M3 Max.

SQL and RESP results with PostgreSQL CPU and memory usage.

Node.js returned 16,616 requests/s for 64-key SQL batches. Go reached 839,678 requests/s for single-key RESP reads. Each result has its own client configuration and SQL baseline.

See results

Is this your workload?

Worth measuring

  • Repeated complete primary-key lookups.
  • A small hot set of whole rows.
  • READ COMMITTED on one writable primary.
  • An application that can call the explicit SQL API.

Keep ordinary SQL

  • Joins, ranges, aggregates, or arbitrary query results.
  • RLS, partitioned, or inherited tables.
  • A database where you cannot install a native extension.
  • Workloads without a measured benefit.

Run a local demo.

Build the extension from your checkout and start a disposable PostgreSQL server with sample rows. Docker keeps the demo separate from your databases.

From the repository root; Docker Compose required
docker compose -f examples/compose.yaml up --build --wait

Get the files, run the queries, and remove the demo. For an existing server, use the installation guide.

Installing on an existing server requires a PostgreSQL restart.

Documentation

{% for item in site.data.navigation %} {{ item.title }}{{ item.description }} {% endfor %}

Before you try it

Does this replace shared_buffers?

No. PostgreSQL caches database pages. This extension separately caches serialized whole rows by primary key. See the read-path comparison.

Does it cache ordinary SELECT queries?

No. Only explicit local_cache.mget calls use the SQL cache. Your existing queries keep PostgreSQL's normal execution path.

Does it replace Redis?

No. The optional RESP2 endpoint is limited. There is no general-purpose Redis command set, TTL, pub/sub, or distributed coordination.

How do I check updates and rollback?

The invalidation guide includes a two-session test. The runnable example checks uncommitted writes, read-your-writes, rollback, and committed updates.