# crunchydata/crunchy-containers architecture

> Architecture diagram of the GitHub repository crunchydata/crunchy-containers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crunchydata/crunchy-containers
- Repository: https://github.com/crunchydata/crunchy-containers

## Overview

Crunchy Container Suite is a collection of PostgreSQL containers and companion tools for deployment, administration, monitoring, connectivity, backup, and restoration. The principal user workflow is to deploy PostgreSQL in a supported environment, then operate it with optional companion containers. The README establishes the suite’s broad purpose; sampled source confirms pgBackRest’s Kubernetes pod-execution flow and pgBadger’s report-generation endpoint. Most companion-container internals were not sampled, so their relationships are limited to documented suite-level links.

Main entry points: [`badger/badgerserver.go`](https://github.com/crunchydata/crunchy-containers/blob/master/badger/badgerserver.go) (pgBadger Server), [`cmd/pgbackrest/main.go`](https://github.com/crunchydata/crunchy-containers/blob/master/cmd/pgbackrest/main.go) (pgBackRest Commands), [`bin/postgres_common/postgres/start.sh`](https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/postgres/start.sh) (PostgreSQL Container), [`bin/pgadmin4/start-pgadmin4.sh`](https://github.com/crunchydata/crunchy-containers/blob/master/bin/pgadmin4/start-pgadmin4.sh) (pgAdmin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_database["PostgreSQL"]
  node_postgres["PostgreSQL Container<br/>[start.sh]"]
  node_gis["PostGIS Container"]
  node_config["Database Configuration<br/>[custom-configs.sh]"]
end

subgraph group_backup["Backup and Restore"]
  node_backrest["pgBackRest Commands<br/>[main.go]"]
  node_backrestrepo["Backup Repository<br/>[pgbackrest-repo.sh]"]
  node_basebackup["Base Backup Restore<br/>[start.sh]"]
  node_pgdump["Dump Backup<br/>[start.sh]"]
  node_pgrestore["Dump Restore<br/>[start.sh]"]
  node_upgrade["Database Upgrade<br/>[start.sh]"]
end

subgraph group_admin["Administration and Monitoring"]
  node_pgadmin["pgAdmin<br/>[start-pgadmin4.sh]"]
  node_pgbadger["pgBadger Server<br/>[badgerserver.go]"]
  node_badgergen["Report Generator<br/>[badger-generate.sh]"]
  node_exporter["Metrics Exporter<br/>[install.sh]"]
end

subgraph group_connectivity["Connectivity and Workloads"]
  node_pgbouncer["PgBouncer<br/>[start.sh]"]
  node_pgpool["Pgpool<br/>[startpgpool.sh]"]
  node_pgbench["Pgbench Workload<br/>[start.sh]"]
end

node_user(("Operator"))
node_kubernetes["Kubernetes API"]

node_user -->|"deploys"| node_postgres
node_user -->|"uses tools"| node_pgadmin
node_user -->|"uses tools"| node_pgbadger
node_backrest -->|"executes in pod"| node_kubernetes
node_pgbadger -->|"runs generator"| node_badgergen

click node_postgres "https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/postgres/start.sh"
click node_gis "https://github.com/crunchydata/crunchy-containers/tree/master/bin/postgres-gis"
click node_config "https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/postgres/custom-configs.sh"
click node_backrest "https://github.com/crunchydata/crunchy-containers/blob/master/cmd/pgbackrest/main.go"
click node_backrestrepo "https://github.com/crunchydata/crunchy-containers/blob/master/bin/pgbackrest-repo/pgbackrest-repo.sh"
click node_basebackup "https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/pgbasebackup_restore/start.sh"
click node_pgdump "https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/pgdump/start.sh"
click node_pgrestore "https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/pgrestore/start.sh"
click node_upgrade "https://github.com/crunchydata/crunchy-containers/blob/master/bin/upgrade/start.sh"
click node_pgadmin "https://github.com/crunchydata/crunchy-containers/blob/master/bin/pgadmin4/start-pgadmin4.sh"
click node_pgbadger "https://github.com/crunchydata/crunchy-containers/blob/master/badger/badgerserver.go"
click node_badgergen "https://github.com/crunchydata/crunchy-containers/blob/master/bin/pgbadger/badger-generate.sh"
click node_exporter "https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/exporter/install.sh"
click node_pgbouncer "https://github.com/crunchydata/crunchy-containers/blob/master/bin/pgbouncer/start.sh"
click node_pgpool "https://github.com/crunchydata/crunchy-containers/blob/master/bin/pgpool/startpgpool.sh"
click node_pgbench "https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/pgbench/start.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_postgres,node_gis,node_config toneBlue
class node_backrest,node_backrestrepo,node_basebackup,node_pgdump,node_pgrestore,node_upgrade toneAmber
class node_pgadmin,node_pgbadger,node_badgergen,node_exporter,node_kubernetes toneMint
class node_pgbouncer,node_pgpool,node_pgbench toneRose
class node_user toneIndigo
```

## Components

### PostgreSQL

- [PostgreSQL Container](https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/postgres/start.sh): `bin/postgres_common/postgres/start.sh`
- [PostGIS Container](https://github.com/crunchydata/crunchy-containers/tree/master/bin/postgres-gis): `bin/postgres-gis`
- [Database Configuration](https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/postgres/custom-configs.sh): `bin/postgres_common/postgres/custom-configs.sh`

### Backup and Restore

- [pgBackRest Commands](https://github.com/crunchydata/crunchy-containers/blob/master/cmd/pgbackrest/main.go): `cmd/pgbackrest/main.go`
- [Backup Repository](https://github.com/crunchydata/crunchy-containers/blob/master/bin/pgbackrest-repo/pgbackrest-repo.sh): `bin/pgbackrest-repo/pgbackrest-repo.sh`
- [Base Backup Restore](https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/pgbasebackup_restore/start.sh): `bin/postgres_common/pgbasebackup_restore/start.sh`
- [Dump Backup](https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/pgdump/start.sh): `bin/postgres_common/pgdump/start.sh`
- [Dump Restore](https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/pgrestore/start.sh): `bin/postgres_common/pgrestore/start.sh`
- [Database Upgrade](https://github.com/crunchydata/crunchy-containers/blob/master/bin/upgrade/start.sh): `bin/upgrade/start.sh`

### Administration and Monitoring

- [pgAdmin](https://github.com/crunchydata/crunchy-containers/blob/master/bin/pgadmin4/start-pgadmin4.sh): `bin/pgadmin4/start-pgadmin4.sh`
- [pgBadger Server](https://github.com/crunchydata/crunchy-containers/blob/master/badger/badgerserver.go): `badger/badgerserver.go`
- [Report Generator](https://github.com/crunchydata/crunchy-containers/blob/master/bin/pgbadger/badger-generate.sh): `bin/pgbadger/badger-generate.sh`
- [Metrics Exporter](https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/exporter/install.sh): `bin/postgres_common/exporter/install.sh`

### Connectivity and Workloads

- [PgBouncer](https://github.com/crunchydata/crunchy-containers/blob/master/bin/pgbouncer/start.sh): `bin/pgbouncer/start.sh`
- [Pgpool](https://github.com/crunchydata/crunchy-containers/blob/master/bin/pgpool/startpgpool.sh): `bin/pgpool/startpgpool.sh`
- [Pgbench Workload](https://github.com/crunchydata/crunchy-containers/blob/master/bin/postgres_common/pgbench/start.sh): `bin/postgres_common/pgbench/start.sh`

### Other components

- **Operator**
- **Kubernetes API**

## Connections

- Operator → PostgreSQL Container: deploys (evidence: `README.md`)
- Operator → pgAdmin: uses tools (evidence: `README.md`)
- Operator → pgBadger Server: uses tools (evidence: `README.md`)
- pgBackRest Commands → Kubernetes API: executes in pod (evidence: `cmd/pgbackrest/main.go`)
- pgBadger Server → Report Generator: runs generator (evidence: `badger/badgerserver.go`)
