pg_kv

Overview

Early release, not production ready. Preload/restart and superuser installation required. Cluster-wide keyspace: nontransactional, not durable or replicated. Grant kv schema usage deliberately; prefixing keys is not tenant access control. Capacity eviction can reset rate-limit allowance.

Version

Build

You can build the RPM / DEB packages for pg_kv using pig build:

pig build pkg pg_kv         # build RPM / DEB packages

Install

You can install pg_kv directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

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

Install the extension using pig or apt/yum/dnf:

pig install pg_kv;          # Install for current active PG version

pig ext install -y pg_kv -v 18  # PG 18
pig ext install -y pg_kv -v 17  # PG 17
pig ext install -y pg_kv -v 16  # PG 16
pig ext install -y pg_kv -v 15  # PG 15

dnf install -y pg_kv_18       # PG 18
dnf install -y pg_kv_17       # PG 17
dnf install -y pg_kv_16       # PG 16
dnf install -y pg_kv_15       # PG 15

apt install -y postgresql-18-pg-kv   # PG 18
apt install -y postgresql-17-pg-kv   # PG 17
apt install -y postgresql-16-pg-kv   # PG 16
apt install -y postgresql-15-pg-kv   # PG 15

Preload:

shared_preload_libraries = 'pg_kv';

Create Extension:

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.