Cloud Architecture

PgCat Deployment Guide (Helm + Kubernetes)

This guide describes the technical steps required to deploy PgCat using the pgcat/pgcat Helm chart on Kubernetes. It covers chart installation, configuration structure, authentication requirements, validation, and operational considerations. This guide is suitable for production environments and can support advanced use cases such as zero-downtime migrations and future read/write splitting.

1. Overview

PgCat is a PostgreSQL proxy and connection pooler supporting:

Connection pooling
SQL-aware routing
Read/write splitting
Sharding support
Mirroring (for migration or traffic shadowing)

This Helm chart converts a YAML configuration into PgCat's required TOML configuration format and injects it into the container. PgCat reads this TOML at startup.

2. Requirements

Kubernetes cluster (any distribution)
Helm v3+
Access to the Helm repository: https://postgresml.github.io/pgcat/
PostgreSQL credentials for upstream cluster(s)

3. Helm Chart Installation

Add the Helm repository

helm repo add pgcat https://postgresml.github.io/pgcat/
helm repo update

Install PgCat

helm install pgcat pgcat/pgcat \
  --namespace pgcat \
  --create-namespace \
  -f values.yaml

To update:

helm upgrade pgcat pgcat/pgcat -n pgcat -f values.yaml

To uninstall:

helm uninstall pgcat -n pgcat

4. Configuration Model

This chart exposes configuration under the top-level key:

configuration:

This YAML is converted into PgCat's internal TOML configuration. PgCat does not accept YAML directly; the chart handles conversion.

Minimal Required Structure

Each pool must include:

name: pool name
pool_mode:
shards: list
servers: inside shards
users: list (mandatory)

If any of these are missing, PgCat will fail to parse TOML and the pod will crash-loop.

5. Example Working Configuration (values.yaml)

This example configures PgCat with one pool, primary + replica, and a required user.

configuration:
  general:
    enable_prometheus_exporter: true
    prometheus_exporter_port: 9930

  pools:
    - name: main
      pool_mode: transaction

      shards:
        - database: postgres
          servers:
            - host: my-primary-db.example.com
              port: 5432
              role: primary
            - host: my-replica-db.example.com
              port: 5432
              role: replica

      users:
        - username: default
          password: default
          pool_size: 20
          statement_timeout: 0

replicaCount: 2

Notes

The users: block is mandatory; PgCat will not start without it.
Passwords can be dummy values; PgCat authenticates to PostgreSQL using upstream credentials from the servers section.
pool_mode: transaction is generally recommended for Kubernetes environments.

6. Connecting Applications to PgCat

Applications connect to PgCat exactly as if it were PostgreSQL:

postgres://default:default@pgcat.pgcat.svc.cluster.local:6432/postgres

Where:

default:default matches the user defined in values.yaml
Host is the PgCat service

PgCat internally connects to PostgreSQL using the hosts defined under servers:.

7. Validating the Rendered Configuration

Before deploying, inspect the generated TOML:

helm template pgcat pgcat/pgcat -f values.yaml | grep -A80 pgcat.toml

Ensure TOML contains:

[pools.<name>] table
[[pools.<name>.shards.servers]] entries
[[pools.<name>.users]] entries

If TOML is malformed, PgCat will log:

Could not parse config file: TOML parse error

This always indicates configuration structure issues.

8. Operational Considerations

Running Multiple Replicas

PgCat is stateless; run ≥2 replicas for high availability.

Config Changes

Modify values.yaml and apply:

helm upgrade pgcat pgcat/pgcat -n pgcat -f values.yaml

PgCat restarts to pick up changes.

Logging Issues

If PgCat crash-loops:

Check logs for TOML errors
Validate the users: block exists
Check indentation in YAML
Ensure roles (primary, replica) are valid

9. Usage in Migration Scenarios

PgCat can act as a stable endpoint during database migration:

Example workflow

Point PgCat to PostgreSQL v11 (source).
Begin migration using pgcopydb + logical replication.
When ready, update PgCat servers: to point to PostgreSQL v14.
Apply Helm upgrade.
Applications reconnect automatically.

This enables near-zero downtime cutover.

10. Summary

Use configuration: for YAML-based definitions; do not use raw pgcat.config.
Always define at least one user under each pool.
Validate TOML output using helm template.
PgCat enables proxy-based migrations and future read/write splitting.
The Helm chart provides a predictable and maintainable deployment pattern.

This guide can be used as the PgCat deployment reference for all Kubernetes environments.