# postgresml/pgcat architecture

> Architecture diagram of the GitHub repository postgresml/pgcat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/postgresml/pgcat
- Repository: https://github.com/postgresml/pgcat

## Overview

##### Project Type and Purpose
- PgCat is a high-performance, multi-threaded PostgreSQL proxy and connection pooler written in Rust. It accepts client connections, pools and routes them to one or more PostgreSQL servers, and provides features such as load balancing, failover, sharding, mirroring, authentication, metrics, and live configuration reloading.

##### Key Architectural Domains
Break the system into four main domains:
a. Client Tier
b. Pooler/Proxy Service (PgCat)
c. PostgreSQL Backend Tier
d. Observability & Deployment

##### Core Components of PgCat
- Listener & Connection Acceptor (src/server.rs)
- Authentication Module (src/auth_passthrough.rs, src/scram.rs)
- Connection Pool Manager (src/pool.rs)
- Query Router & Parser (src/query_router.rs, sqlparser crate)
- Sharding Engine (src/sharding.rs)
- Mirroring & Proxy Plugins (src/plugins/*)
- Health & Failover Checker (built into query routing and pool logic)
- Metrics & Admin Interface
- Admin DB endpoint (pgbouncer/pgcat databases) (src/admin.rs)
- HTTP `/metrics` for Prometheus (src/prometheus.rs)
- Configuration Loader & Hot-Reload (src/config.rs & SIGHUP support)
- TLS Layer (src/tls.rs)
- Logging (src/logger.rs)

##### Relationships and Data Flow
- Clients issue SQL → Listener → Authentication → Pooled Connection
- Query text flows into Query Router → decides:
- Primary vs. replica (load balancing)
- Shard selection via explicit SET SHARD or comment parsing or automatic SQL parse
- Mirroring (duplicate to multiple backends if enabled)
- Connection Pool Manager dispatches the query on a worker thread (Tokio runtime)
- Worker thread forwards query to chosen Postgres server(s) over TCP/TLS
- Responses flow back to the client
- Health Checker runs periodic “ping” queries on each server and updates pool state
- Configuration changes (pgcat.toml) trigger hot-reload; Plugins and pool settings update on the fly
- Metrics collector exposes counters/gauges via HTTP and in-DB tables for Grafana/Prometheus

##### External Systems
- PostgreSQL Instances: Primary, Replicas, Shards
- Prometheus scrapes `/metrics` endpoint
- Grafana imports the provided dashboard JSON (grafana_dashboard.json)
- Kubernetes/Helm (charts/pgcat) or Docker Compose (docker-compose.yml, dev/docker-compose.yaml) for deployment

##### Architectural Patterns & Design Principles
- Asynchronous, multi-threaded event loop (Tokio)
- Modular plugin architecture (Rust traits in src/plugins)
- Configuration as code (TOML file, live reloading)
- Separation of concerns: authentication, routing, pooling, health, metrics
- Fail-fast and self-healing: automatic ban and re-enable of unhealthy servers

## Diagram (Mermaid)

```mermaid
graph TB

    subgraph "Client Tier"
        ClientApp["Client App (ORM, CLI)"]:::client
    end

    subgraph "PgCat Proxy"
        Listener["Listener & Connection Acceptor"]:::service
        TLS["TLS Layer"]:::service
        Auth["Authentication Module"]:::service
        PoolMgr["Connection Pool Manager"]:::service
        Router["Query Router & Parser"]:::service
        Sharder["Sharding Engine"]:::service
        Plugins["Mirroring & Proxy Plugins"]:::service
        Health["Health & Failover Checker"]:::service
        Config["Configuration Loader & Hot-Reload"]:::service
        Admin["Admin DB Endpoint"]:::control
        Metrics["HTTP /metrics"]:::obs
        Logger["Logging"]:::service
    end

    subgraph "PostgreSQL Backend Tier"
        Primary[(Primary DB)]:::db
        Replica[(Read Replica)]:::db
        Shard1[(Shard 1)]:::db
        Shard2[(Shard 2)]:::db
    end

    subgraph "Observability & Deployment"
        Prom["Prometheus"]:::obs
        Graf["Grafana"]:::obs
        Docker["Docker Compose"]:::deploy
        Helm["Helm Chart"]:::deploy
    end

    ClientApp -->|"PostgreSQL wire"| Listener
    Listener -->|TLS handshake| TLS
    TLS -->|decrypted| Auth
    Auth -->|authenticated| PoolMgr
    PoolMgr -->|dispatch| Router
    Router -->|parse & route| Sharder
    Router -->|route & mirror| Plugins

    Router -->|TCP/TLS| Primary
    Router -->|TCP/TLS| Replica
    Router -->|TCP/TLS| Shard1
    Router -->|TCP/TLS| Shard2

    Health <-->|ping/health-check| Primary
    Health <-->|ping/health-check| Replica
    Health <-->|ping/health-check| Shard1
    Health <-->|ping/health-check| Shard2

    Config -->|"SIGHUP"| Listener
    Config --> Auth
    Config --> PoolMgr
    Config --> Router
    Config --> Sharder
    Config --> Plugins
    Config --> Health
    Config --> Metrics

    Metrics -->|"HTTP scrape"| Prom
    Prom -->|"dashboard JSON"| Graf

    classDef client fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1
    classDef service fill:#BBDEFB,stroke:#42A5F5,color:#1565C0
    classDef control fill:#C8E6C9,stroke:#66BB6A,color:#1B5E20
    classDef obs fill:#FFE0B2,stroke:#FFA726,color:#E65100
    classDef deploy fill:#E0E0E0,stroke:#BDBDBD,color:#424242
    classDef db fill:#FFF9C4,stroke:#FDD835,color:#F57F17

    click Listener "https://github.com/postgresml/pgcat/blob/main/src/server.rs"
    click Auth "https://github.com/postgresml/pgcat/blob/main/src/auth_passthrough.rs"
    click Auth "https://github.com/postgresml/pgcat/blob/main/src/scram.rs"
    click PoolMgr "https://github.com/postgresml/pgcat/blob/main/src/pool.rs"
    click Router "https://github.com/postgresml/pgcat/blob/main/src/query_router.rs"
    click Sharder "https://github.com/postgresml/pgcat/blob/main/src/sharding.rs"
    click Plugins "https://github.com/postgresml/pgcat/blob/main/src/mirrors.rs"
    click Plugins "https://github.com/postgresml/pgcat/blob/main/src/plugins/mod.rs"
    click Plugins "https://github.com/postgresml/pgcat/blob/main/src/plugins/intercept.rs"
    click Plugins "https://github.com/postgresml/pgcat/blob/main/src/plugins/prewarmer.rs"
    click Plugins "https://github.com/postgresml/pgcat/blob/main/src/plugins/query_logger.rs"
    click Plugins "https://github.com/postgresml/pgcat/blob/main/src/plugins/table_access.rs"
    click Admin "https://github.com/postgresml/pgcat/blob/main/src/admin.rs"
    click Metrics "https://github.com/postgresml/pgcat/blob/main/src/prometheus.rs"
    click Config "https://github.com/postgresml/pgcat/blob/main/src/config.rs"
    click TLS "https://github.com/postgresml/pgcat/blob/main/src/tls.rs"
    click Logger "https://github.com/postgresml/pgcat/blob/main/src/logger.rs"
```
