PgPaw lets clients read Postgres through plain SQL without sending every read to your upstream database. It runs as a small HTTP service, keeps a local pglite-rs logical replica, and serves two read paths from the same query:
- a cacheable JSON snapshot;
- a live Server-Sent Events stream.
PgPaw does not handle writes. Your application still writes to upstream Postgres. Logical replication brings committed changes into PgPaw, and PgPaw uses those changes to invalidate snapshots and push live deltas.
What PgPaw gives you
| Need | PgPaw behavior |
|---|---|
| Read SQL over HTTP |
POST /query accepts one read-only PostgreSQL
SELECT.
|
| Shared public snapshots |
Public queries redirect to
/q/{hash}/{version}.
|
| Realtime updates |
POST /query?live=true streams snapshot and
row deltas.
|
| Postgres-native private data | RLS and table grants decide whether a query is private and never stored in the shared snapshot cache. |
| Operator visibility |
PgPaw logs startup, bind port, query decisions, cache
events, CDC, health, and errors at INFO or
higher.
|
Public vs private queries
PgPaw decides whether a query is public from the replicated Postgres catalog.
-
Public: every touched table has RLS disabled and
PUBLIC SELECT. -
Private: at least one touched table has RLS enabled or lacks
PUBLIC SELECT.
Public queries use the shared snapshot cache. Private queries
require a bearer token, run under the token's Postgres role, and
return inline JSON with
Cache-Control: private, no-store.
HTTP cache behavior is intentionally split:
-
public cursor responses use
Cache-Control: public, max-age=259200; -
private query responses use
Cache-Control: private, no-store; - live streams use
Cache-Control: no-store.
Start here
- Install PgPaw
- Run the quickstart
- Read the HTTP API
- Configure RLS and JWT auth
- Understand Cache-Control
- Check logs and operations output
The important boundary
PgPaw is a read layer. Keep these responsibilities outside PgPaw:
- writes and mutations;
- migrations;
- business logic;
- background jobs;
- long-term durable truth.
Keep those in your application and upstream Postgres. PgPaw watches committed changes and makes reads fast, cacheable, and live.