Getting Started

This guide walks you through setting up PgCache as a caching proxy in front of your PostgreSQL database.

Not sure yet whether PgCache suits your workload? Check first with the Fit Analyzer: drop in a pg_stat_statements export or a PostgreSQL log and it shows which of your queries PgCache would cache, before you install anything. It runs in your browser, and nothing is uploaded.

Prerequisites

Before installing PgCache, ensure your environment meets these requirements:

  • PostgreSQL 16+ as your origin database (why 16+?)
  • Logical replication enabled on the origin (wal_level = logical)
  • Docker for running PgCache

Configure the Origin Database

PgCache uses PostgreSQL logical replication to keep its cache synchronized. Your origin database needs logical replication enabled and a user with sufficient permissions.

Enable Logical Replication

Add or update the following settings in your PostgreSQL configuration (postgresql.conf) and restart the server:

wal_level = logical
max_replication_slots = 10
max_wal_senders = 10

If you’re running a managed PostgreSQL service (AWS RDS, Google Cloud SQL, Neon, etc.), check your provider’s documentation for enabling logical replication.

Database User Permissions

PgCache automatically creates and manages the publication and replication slot it needs on the origin database. The database user that PgCache connects with must have permission to do so:

  • Superuser, or
  • REPLICATION role attribute plus ownership of (or CREATE privilege on) the tables to be published

For example, to grant a dedicated user the required permissions:

ALTER ROLE pgcache_user REPLICATION;

On managed services where superuser access is unavailable, consult your provider’s documentation for granting replication permissions.

Try It in One Command

On a laptop or dev machine with Docker, the try script does the rest of this page for you:

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

It finds your database (from --upstream, DATABASE_URL, a .env file, the PG* variables, or a running PostgreSQL container), runs the origin check described below, starts PgCache as a container named pgcache-try, and prints the connection string to switch to. Pass the origin explicitly with bash -s -- --upstream postgres://user@host:5432/db, watch the hit rate with bash -s -- status, and remove everything with bash -s -- stop. The script is short and readable; the rest of this page is what it automates.

Check the Origin

Before starting the proxy, have the image check that the origin is ready. It reports each requirement on this page with a fix, worded for your host (self-managed, RDS, Cloud SQL, or Neon), and exits with status 1 if any fail:

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

Warnings do not block a start, but they name what will not be cached: tables without a primary key, views, and tables the role does not own. Tables with row-level security fail the check, since PgCache does not support RLS yet; exclude them with ALLOWED_TABLES. See Docker → Checking the Origin for a sample report.

Install with Docker

PgCache is distributed as a Docker image. The container includes an embedded PostgreSQL instance for the cache database, so there’s nothing else to set up.

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

This starts PgCache listening on port 5432 (proxy) and port 9090 (Prometheus metrics), proxying to your origin database.

For production deployment — Docker Compose, mounting configuration and TLS certificates, health checks, and restart policy — see Deploy → Docker.

Deploy on AWS

PgCache is available as a pre-built AMI on the AWS Marketplace. The AMI includes PgCache and an embedded PostgreSQL cache database, configured automatically at launch via AWS SSM Parameter Store. Subscribe directly from the Marketplace listing, then see the AWS Marketplace guide for setup instructions.

Connect Your Application

Update your application’s database connection string to point at PgCache instead of your origin database directly:

# Before
DATABASE_URL=postgres://user:password@db-host:5432/myapp

# After — just change the host (and port if needed)
DATABASE_URL=postgres://user:password@pgcache-host:5432/myapp

Your application connects to PgCache using the same credentials it would use for the origin database. PgCache passes authentication through to the origin transparently.

Verify It Works

Once your application is connected through PgCache, you can verify caching is active by checking the metrics endpoint. The Docker image exposes Prometheus metrics on port 9090 by default.

Query the endpoint:

curl http://localhost:9090/metrics | grep pgcache_queries

Look for pgcache_queries_cache_hit and pgcache_queries_cache_miss counters to confirm caching is active. See Monitoring for the full list of available metrics.

Next Steps

Continue reading to learn more about PgCache:

  • Configuration — Full reference for every setting (TOML, CLI, and Docker environment variables), including memory and disk limits and eviction policy, table allowlists, pinned queries, and TLS.
  • How Caching Works — What gets cached, how CDC invalidation works, and the consistency model.
  • Monitoring — Set up Prometheus metrics and alerting.
  • Compatibility — Supported PostgreSQL versions, which query patterns are cached, and known limitations.