Getting Started

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

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.

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. Contact us for access, or 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 cache size 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.