Architecture

How pg_redis, the in-process BGWorker host, and the shared gateway core fit together.

pg_redis makes PostgreSQL speak Redis RESP. The primary product shape is extensions inside Postgres — clients hit RESP on the same host as the database. No separate gateway process required.

The same redis_gateway_core also ships as a standalone service (pg_redis_gw/redis_gateway) for external deployment or local testing.

Pieces

Piece	Role
`pg_redis`	SQL storage (schema `redis`)
`pg_redis_gw_host`	pgrx BGWorker hosting RESP inside Postgres
`pg_redis_gw`	Shared core + optional standalone binary

North star: install the extension(s), preload the host, talk Redis — storage and protocol co-located in PostgreSQL.

Layers

Layer	Where	Responsibility
Storage / semantics	`pg_redis/` (`redis.*` SQL)	Key/value rules, persistence, SQL API
Dispatch + encoding	`pg_redis_gw/redis_gateway_core`	Parse args, call SQL/session, RESP replies
Hosting	`pg_redis_gw_host` / `redis_gateway`	Listen + session; no command logic
Compat	`compat/allowlist.txt` + `STATUS.md`	Named Valkey tests that must stay green

Prefer Redis semantics as redis.* SQL; the gateway binds params and encodes protocol only. Both the in-process BGWorker and the standalone binary share redis_gateway_core — fix behavior there once.

Extensions

Extension	Purpose
`pg_redis`	Storage: `redis.*` SQL + `pg_cron` TTL sweeper
`pg_redis_gw_host`	RESP BGWorker — needs `shared_preload_libraries=pg_cron,pg_redis_gw_host`

Postgres forbids pg_* schema names — storage lives in schema redis. Extension names stay pg_redis / pg_redis_gw_host.

Today that’s two extensions (storage + host). The experience we’re aiming for is still “install and go”: one Postgres, Redis language on the wire.

Layout

pg_redis/ — SQL extension (CREATE EXTENSION pg_redis)
pg_redis_gw_host/ — In-process RESP BGWorker
pg_redis_gw/ — Gateway core + standalone binary
docker/ — Container image + compose stack
compat/ — Valkey allowlist suite
docs/ — This documentation site (Blume)
bench/ — Benchmark scripts and published results

Design rules

Schema name is redis (not pg_redis) — Postgres reserves pg_* schemas.
Prefer Redis semantics as redis.* SQL; gateway binds params / protocol only.
Default docs and make postgres-up target the in-process path; keep the standalone binary working — both share redis_gateway_core.
When adding Redis commands, follow Implementing a Redis command and update compat/STATUS.md.