# nuo534202/pgcpp architecture

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

- Interactive diagram: https://gitdiagram.com/nuo534202/pgcpp
- Repository: https://github.com/nuo534202/pgcpp

## Overview

pgcpp is a C++20 reimplementation of PostgreSQL’s database server and client tools. The main workflow is a client sending SQL to the server, which parses and analyzes it, rewrites views and security policies, plans it, executes it against access methods and storage, then returns results. The tree and README document broader administration, replication, and backup capabilities. Sampled source supports several runtime details, but not every subsystem’s wiring; links for unsampled stages are limited to the architecture and module roles evident in the repository.

Main entry points: [`src/protocol/postgres.cpp`](https://github.com/nuo534202/pgcpp/blob/main/src/protocol/postgres.cpp) (Client protocol), [`src/rewrite/rewrite_handler.cpp`](https://github.com/nuo534202/pgcpp/blob/main/src/rewrite/rewrite_handler.cpp) (Rewrite and RLS), [`src/executor/exec_main.cpp`](https://github.com/nuo534202/pgcpp/blob/main/src/executor/exec_main.cpp) (Plan executor), [`src/tools/psql_client.cpp`](https://github.com/nuo534202/pgcpp/blob/main/src/tools/psql_client.cpp) (psql client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server lifecycle"]
  node_server_main["Server entry<br/>[main.cpp]"]
  node_postmaster["Postmaster<br/>[postmaster.cpp]"]
  node_bootstrap["Cluster bootstrap<br/>[bootstrap.cpp]"]
  node_protocol["Client protocol<br/>[postgres.cpp]"]
end

subgraph group_query["Query processing"]
  node_parser["Parse and analyze<br/>[analyze.cpp]"]
  node_rewrite["Rewrite and RLS"]
  node_planner["Query planner<br/>[planner.cpp]"]
  node_executor["Plan executor<br/>[exec_main.cpp]"]
  node_commands["SQL commands<br/>[tablecmds.cpp]"]
end

subgraph group_data["Data and transactions"]
  node_catalog[("System catalog<br/>[catalog.cpp]")]
  node_access["Heap and indexes<br/>[heapam.cpp]"]
  node_buffers["Buffer manager<br/>[bufmgr.cpp]"]
  node_disk[("Database files<br/>[md.cpp]")]
  node_transactions["Transactions and WAL<br/>[xact.cpp]"]
end

subgraph group_operations["Operations and replication"]
  node_replication["Replication<br/>[logical.cpp]"]
  node_apply_worker["Apply worker<br/>[worker.cpp]"]
end

subgraph group_clients["Client tools"]
  node_psql["psql client<br/>[psql_client.cpp]"]
  node_admin["Admin utilities<br/>[createdb.cpp]"]
  node_dump["Dump and restore<br/>[pg_dump.cpp]"]
  node_backup["Base backup<br/>[pg_basebackup.cpp]"]
end

node_user(("SQL user"))

node_user -->|"enters SQL"| node_psql
node_psql -->|"sends query"| node_protocol
node_server_main -->|"dispatches bootstrap"| node_bootstrap
node_server_main -->|"starts server"| node_postmaster
node_psql -->|"receives results"| node_protocol
node_protocol -->|"dispatches SQL"| node_parser
node_parser -->|"passes query"| node_rewrite
node_rewrite -->|"passes rewritten query"| node_planner
node_rewrite -->|"looks up views"| node_catalog
node_planner -->|"creates plan"| node_executor
node_executor -->|"runs scans"| node_access
node_executor -->|"dispatches utility"| node_commands
node_access -->|"reads and writes pages"| node_buffers
node_buffers -->|"reads and writes blocks"| node_disk
node_transactions -->|"records transactional state"| node_catalog
node_transactions -->|"supplies WAL"| node_replication
node_replication -->|"manages workers"| node_apply_worker
node_admin -->|"issues commands"| node_protocol
node_dump -->|"queries database"| node_protocol
node_backup -->|"requests backup"| node_protocol

click node_psql "https://github.com/nuo534202/pgcpp/blob/main/src/tools/psql_client.cpp"
click node_server_main "https://github.com/nuo534202/pgcpp/blob/main/src/server/main.cpp"
click node_postmaster "https://github.com/nuo534202/pgcpp/blob/main/src/server/postmaster.cpp"
click node_bootstrap "https://github.com/nuo534202/pgcpp/blob/main/src/server/bootstrap.cpp"
click node_protocol "https://github.com/nuo534202/pgcpp/blob/main/src/protocol/postgres.cpp"
click node_parser "https://github.com/nuo534202/pgcpp/blob/main/src/parser/analyze.cpp"
click node_rewrite "https://github.com/nuo534202/pgcpp/blob/main/src/rewrite/rewrite_handler.cpp"
click node_planner "https://github.com/nuo534202/pgcpp/blob/main/src/optimizer/plan/planner.cpp"
click node_executor "https://github.com/nuo534202/pgcpp/blob/main/src/executor/exec_main.cpp"
click node_commands "https://github.com/nuo534202/pgcpp/blob/main/src/commands/tablecmds.cpp"
click node_catalog "https://github.com/nuo534202/pgcpp/blob/main/src/catalog/catalog.cpp"
click node_access "https://github.com/nuo534202/pgcpp/blob/main/src/access/heap/heapam.cpp"
click node_buffers "https://github.com/nuo534202/pgcpp/blob/main/src/storage/buffer/bufmgr.cpp"
click node_disk "https://github.com/nuo534202/pgcpp/blob/main/src/storage/smgr/md.cpp"
click node_transactions "https://github.com/nuo534202/pgcpp/blob/main/src/transaction/xact.cpp"
click node_replication "https://github.com/nuo534202/pgcpp/blob/main/src/replication/logical.cpp"
click node_apply_worker "https://github.com/nuo534202/pgcpp/blob/main/src/replication/worker.cpp"
click node_admin "https://github.com/nuo534202/pgcpp/blob/main/tools/createdb/createdb.cpp"
click node_dump "https://github.com/nuo534202/pgcpp/blob/main/tools/pg_dump/pg_dump.cpp"
click node_backup "https://github.com/nuo534202/pgcpp/blob/main/tools/pg_basebackup/pg_basebackup.cpp"

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_server_main,node_postmaster,node_bootstrap,node_protocol,node_user toneBlue
class node_parser,node_rewrite,node_planner,node_executor,node_commands toneAmber
class node_catalog,node_access,node_buffers,node_disk,node_transactions toneMint
class node_replication,node_apply_worker toneRose
class node_psql,node_admin,node_dump,node_backup toneIndigo
```

## Components

### Server lifecycle

- [Server entry](https://github.com/nuo534202/pgcpp/blob/main/src/server/main.cpp): `src/server/main.cpp`
- [Postmaster](https://github.com/nuo534202/pgcpp/blob/main/src/server/postmaster.cpp): `src/server/postmaster.cpp`
- [Cluster bootstrap](https://github.com/nuo534202/pgcpp/blob/main/src/server/bootstrap.cpp): `src/server/bootstrap.cpp`
- [Client protocol](https://github.com/nuo534202/pgcpp/blob/main/src/protocol/postgres.cpp): `src/protocol/postgres.cpp`

### Query processing

- [Parse and analyze](https://github.com/nuo534202/pgcpp/blob/main/src/parser/analyze.cpp): `src/parser/analyze.cpp`
- [Rewrite and RLS](https://github.com/nuo534202/pgcpp/blob/main/src/rewrite/rewrite_handler.cpp): `src/rewrite/rewrite_handler.cpp`
- [Query planner](https://github.com/nuo534202/pgcpp/blob/main/src/optimizer/plan/planner.cpp): `src/optimizer/plan/planner.cpp`
- [Plan executor](https://github.com/nuo534202/pgcpp/blob/main/src/executor/exec_main.cpp): `src/executor/exec_main.cpp`
- [SQL commands](https://github.com/nuo534202/pgcpp/blob/main/src/commands/tablecmds.cpp): `src/commands/tablecmds.cpp`

### Data and transactions

- [System catalog](https://github.com/nuo534202/pgcpp/blob/main/src/catalog/catalog.cpp): `src/catalog/catalog.cpp`
- [Heap and indexes](https://github.com/nuo534202/pgcpp/blob/main/src/access/heap/heapam.cpp): `src/access/heap/heapam.cpp`
- [Buffer manager](https://github.com/nuo534202/pgcpp/blob/main/src/storage/buffer/bufmgr.cpp): `src/storage/buffer/bufmgr.cpp`
- [Database files](https://github.com/nuo534202/pgcpp/blob/main/src/storage/smgr/md.cpp): `src/storage/smgr/md.cpp`
- [Transactions and WAL](https://github.com/nuo534202/pgcpp/blob/main/src/transaction/xact.cpp): `src/transaction/xact.cpp`

### Operations and replication

- [Replication](https://github.com/nuo534202/pgcpp/blob/main/src/replication/logical.cpp): `src/replication/logical.cpp`
- [Apply worker](https://github.com/nuo534202/pgcpp/blob/main/src/replication/worker.cpp): `src/replication/worker.cpp`

### Client tools

- [psql client](https://github.com/nuo534202/pgcpp/blob/main/src/tools/psql_client.cpp): `src/tools/psql_client.cpp`
- [Admin utilities](https://github.com/nuo534202/pgcpp/blob/main/tools/createdb/createdb.cpp): `tools/createdb/createdb.cpp`
- [Dump and restore](https://github.com/nuo534202/pgcpp/blob/main/tools/pg_dump/pg_dump.cpp): `tools/pg_dump/pg_dump.cpp`
- [Base backup](https://github.com/nuo534202/pgcpp/blob/main/tools/pg_basebackup/pg_basebackup.cpp): `tools/pg_basebackup/pg_basebackup.cpp`

### Other components

- **SQL user**

## Connections

- SQL user → psql client: enters SQL
- psql client → Client protocol: sends query
- Server entry → Cluster bootstrap: dispatches bootstrap
- Server entry → Postmaster: starts server
- psql client → Client protocol: receives results
- Client protocol → Parse and analyze: dispatches SQL
- Parse and analyze → Rewrite and RLS: passes query
- Rewrite and RLS → Query planner: passes rewritten query
- Rewrite and RLS → System catalog: looks up views
- Query planner → Plan executor: creates plan
- Plan executor → Heap and indexes: runs scans
- Plan executor → SQL commands: dispatches utility
- Heap and indexes → Buffer manager: reads and writes pages
- Buffer manager → Database files: reads and writes blocks
- Transactions and WAL → System catalog: records transactional state
- Transactions and WAL → Replication: supplies WAL
- Replication → Apply worker: manages workers
- Admin utilities → Client protocol: issues commands
- Dump and restore → Client protocol: queries database
- Base backup → Client protocol: requests backup