pgcache/pgcache repository overview

⁠PgCache: smart read replica for PostgreSQL

Cache your hottest reads and keep them fresh automatically. PgCache is a wire-compatible Postgres proxy. It serves cacheable reads from its own working set, keeps that set in step with your database through logical replication, and forwards everything else to the origin unchanged. One connection string, no code changes.

⁠Try it in one command

On a laptop or dev machine with Docker:

curl -fsSL https://pgcache.com/try.sh | bash

It finds your database (DATABASE_URL, a .env file, the PG* variables, or a running Postgres container), checks the origin is ready and tells you what to fix, starts this image as a container named pgcache-try, and prints the connection string to switch to.

curl -fsSL https://pgcache.com/try.sh | bash -s -- status   # live hit rate
curl -fsSL https://pgcache.com/try.sh | bash -s -- stop     # remove the container

The script is plain bash. Read it first⁠ if you like.

⁠Run the image directly

docker run -d -p 5432:5432 -p 9090:9090 pgcache/pgcache \
  --upstream postgres://user:password@your-db-host:5432/myapp

• 5432: Postgres wire protocol. Point your app here instead of at the database.
• 9090: Prometheus metrics and /healthz. It's unauthenticated, so keep it off the public internet.

The image bundles its own cache database, so there's nothing else to run.

⁠Docker Compose

services:
  pgcache:
    image: pgcache/pgcache:0.7.0
    restart: always
    ports: ["5432:5432", "9090:9090"]
    environment:
      UPSTREAM_URL: postgres://user@db:5432/myapp
      ORIGIN_PASSWORD: ${ORIGIN_PASSWORD}

⁠Check the origin first

docker run --rm pgcache/pgcache check \
  --upstream postgres://user:password@your-db-host:5432/myapp

It reports each requirement with a fix worded for your host (self-managed, RDS and Aurora, Cloud SQL, or Neon) and leaves nothing behind.

⁠Requirements

• PostgreSQL 16, 17 or 18 as the origin
• Logical replication on the origin (wal_level = logical)
• A role with REPLICATION that owns the tables to cache, or a superuser

⁠Will it fit your workload?

Find out before you install anything. The Fit Analyzer⁠ takes a pg_stat_statements export and shows which of your queries PgCache would serve from cache. It runs in your browser, and nothing is uploaded.

⁠Tags

• latest, 0.7.0: multi-arch (amd64 and arm64)
• <version>-amd64, <version>-arm64: single architecture

In production, use a version tag like 0.7.0 rather than latest, so a restart never upgrades you by surprise.

⁠Docs and links

• Getting started⁠
• Production Docker setup⁠: Compose, TLS, health checks
• Configuration reference⁠: every setting as an env var, CLI flag or TOML
• Source on GitHub⁠ (Elastic License 2.0)
• AWS Marketplace⁠: 30-day free trial
• Website⁠

⁠Support

Ask in Discord⁠ or email [email protected]⁠.