pg_kv

pg_kv : Shared-memory key/value cache, token-bucket rate limits and sorted sets.

Overview

Packages

Source

pig build pkg pg_kv;		# build rpm/deb

Install

Make sure PGDG and PIGSTY repo available:

pig repo add pgsql -u   # add both repo and update cache

Install this extension with pig:

pig install pg_kv;		# install via package name, for the active PG version

pig install pg_kv -v 18;   # install for PG 18
pig install pg_kv -v 17;   # install for PG 17
pig install pg_kv -v 16;   # install for PG 16
pig install pg_kv -v 15;   # install for PG 15

Config this extension to shared_preload_libraries:

shared_preload_libraries = 'pg_kv';

Create this extension with:

CREATE EXTENSION pg_kv;

Usage

Sources:

• Official source
• Official source
• Official source
• Official source

pg_kv 0.1.0 provides a shared-memory cache, counters, token-bucket rate limiting and sorted sets. This early release targets PostgreSQL 15–18 and is not production ready.

Core Workflow

Add the library to the existing preload list and restart PostgreSQL before installing the extension as a superuser:

shared_preload_libraries = 'pg_kv'

CREATE EXTENSION pg_kv;
SELECT kv.set('app:session:42', '{"user":1}', interval '30 minutes');
SELECT kv.get('app:session:42');
SELECT kv.ttl('app:session:42');
SELECT kv.incr('app:views:7');
SELECT kv.rate_limit('app:api:42', 100, interval '1 minute');
SELECT kv.zadd('app:leaderboard', 'player:9', 1520);
SELECT * FROM kv.zrange('app:leaderboard', 0, 9, reverse => true);
SELECT * FROM kv.stats();

Installation fails if the library was not preloaded. Grant schema kv usage only to intended callers. The keyspace is shared across every database in the cluster; prefixes organize keys but do not enforce tenant isolation.

Operations and Capacity

kv.ttl returns milliseconds, -1 for a permanent key and -2 for a missing key. kv.expire changes expiry, kv.del removes a key, and kv.rate_limit_info reports allowance and retry timing. Sorted sets also support kv.zscore, kv.zrank, kv.zrevrank, kv.zincrby, kv.zcard and kv.zrem.

Restart settings include pg_kv.max_entries, pg_kv.max_key_bytes, pg_kv.max_value_bytes, pg_kv.shards, pg_kv.sweep_interval_ms, pg_kv.max_zset_members and pg_kv.max_member_bytes. Storage is bounded; oversize values fail, and pressure can evict cached keys. kv.flush is an administrative operation unavailable to the public role by default.

Durability Boundary

Cache changes survive transaction rollback but disappear on a server restart or crash. They are not WAL logged or replicated; a standby has its own cache. Use this for disposable state, not authoritative records or a globally coordinated limiter across independent servers.