# wanglinn/postgres architecture

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

- Interactive diagram: https://gitdiagram.com/wanglinn/postgres
- Repository: https://github.com/wanglinn/postgres

## Overview

PostgreSQL is an object-relational database server. Its principal workflow accepts SQL through a client connection, executes queries, and returns results; the sampled portal code explicitly dispatches query execution to the executor. The README documents major capabilities, including transactions, foreign keys, subqueries, triggers, and user-defined types and functions. The graph preserves these product areas, plus storage, procedural languages, and replication. Many implementation paths are represented by their exact tree directories because their source was not sampled; links without direct evidence are dashed.

Main entry points: [`src/backend/executor`](https://github.com/wanglinn/postgres/tree/master/src/backend/executor) (Query executor), [`src/backend/parser`](https://github.com/wanglinn/postgres/tree/master/src/backend/parser) (SQL parsing), [`src/backend/catalog/storage.c`](https://github.com/wanglinn/postgres/blob/master/src/backend/catalog/storage.c) (Relation storage), [`src/backend/access/transam`](https://github.com/wanglinn/postgres/tree/master/src/backend/access/transam) (Transactions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["Query processing"]
  node_parser["SQL parsing"]
  node_rewrite["Query rewriting<br/>[rewriteHandler.c]"]
  node_planner["Query planning"]
  node_portal["Portal execution<br/>[pquery.c]"]
  node_executor["Query executor"]
  node_queryids["Query fingerprinting<br/>[queryjumblefuncs.c]"]
end

subgraph group_engine["Database engine"]
  node_transactions["Transactions"]
  node_heap["Heap tables"]
  node_indexes["Index access methods"]
  node_storage["Relation storage<br/>[storage.c]"]
  node_catalog[("System catalogs")]
  node_sharedheaders["Core runtime interfaces"]
end

subgraph group_features["SQL capabilities"]
  node_foreignkeys["Foreign keys<br/>[constraint.c]"]
  node_triggers["Triggers<br/>[trigger.c]"]
  node_types["User-defined types<br/>[typecmds.c]"]
  node_ltree["Ltree search types"]
end

subgraph group_interfaces["Interfaces and extensions"]
  node_connection["Client connections"]
  node_plpgsql["PL/pgSQL<br/>[pl_handler.c]"]
  node_fdw["Foreign data wrapper"]
  node_replication["Logical replication"]
  node_basebackup["Base backups"]
end

node_client(("SQL client"))

node_client -.->|"connects"| node_connection
node_connection -.->|"submits SQL"| node_parser
node_parser -.->|"produces queries"| node_rewrite
node_rewrite -.->|"rewrites queries"| node_planner
node_planner -.->|"plans statements"| node_portal
node_portal -->|"runs queries"| node_executor
node_executor -.->|"returns results"| node_client
node_executor -.->|"scans tables"| node_heap
node_executor -.->|"uses indexes"| node_indexes
node_executor -.->|"runs in"| node_transactions
node_heap -.->|"uses storage"| node_storage
node_storage -.->|"logs changes"| node_transactions
node_executor -.->|"checks constraints"| node_foreignkeys
node_executor -.->|"fires triggers"| node_triggers
node_parser -.->|"resolves types"| node_types
node_executor -.->|"calls functions"| node_plpgsql
node_executor -.->|"dispatches scans"| node_fdw
node_transactions -.->|"supports changes"| node_replication
node_storage -.->|"supplies files"| node_basebackup
node_queryids -.->|"identifies queries"| node_executor
node_parser -.->|"exposes type syntax"| node_ltree
node_sharedheaders -->|"declares interfaces"| node_storage
node_catalog -.->|"records definitions"| node_types

click node_connection "https://github.com/wanglinn/postgres/tree/master/src/backend/libpq"
click node_parser "https://github.com/wanglinn/postgres/tree/master/src/backend/parser"
click node_rewrite "https://github.com/wanglinn/postgres/blob/master/src/backend/rewrite/rewriteHandler.c"
click node_planner "https://github.com/wanglinn/postgres/tree/master/src/backend/optimizer"
click node_portal "https://github.com/wanglinn/postgres/blob/master/src/backend/tcop/pquery.c"
click node_executor "https://github.com/wanglinn/postgres/tree/master/src/backend/executor"
click node_queryids "https://github.com/wanglinn/postgres/blob/master/src/backend/nodes/queryjumblefuncs.c"
click node_transactions "https://github.com/wanglinn/postgres/tree/master/src/backend/access/transam"
click node_heap "https://github.com/wanglinn/postgres/tree/master/src/backend/access/heap"
click node_indexes "https://github.com/wanglinn/postgres/tree/master/src/backend/access"
click node_storage "https://github.com/wanglinn/postgres/blob/master/src/backend/catalog/storage.c"
click node_catalog "https://github.com/wanglinn/postgres/tree/master/src/backend/catalog"
click node_foreignkeys "https://github.com/wanglinn/postgres/blob/master/src/backend/commands/constraint.c"
click node_triggers "https://github.com/wanglinn/postgres/blob/master/src/backend/commands/trigger.c"
click node_types "https://github.com/wanglinn/postgres/blob/master/src/backend/commands/typecmds.c"
click node_plpgsql "https://github.com/wanglinn/postgres/blob/master/src/pl/plpgsql/src/pl_handler.c"
click node_fdw "https://github.com/wanglinn/postgres/tree/master/contrib/postgres_fdw"
click node_replication "https://github.com/wanglinn/postgres/tree/master/src/backend/replication/logical"
click node_basebackup "https://github.com/wanglinn/postgres/tree/master/src/backend/backup"
click node_ltree "https://github.com/wanglinn/postgres/tree/master/contrib/ltree"
click node_sharedheaders "https://github.com/wanglinn/postgres/tree/master/src/include"

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_parser,node_rewrite,node_planner,node_portal,node_executor,node_queryids,node_client toneBlue
class node_transactions,node_heap,node_indexes,node_storage,node_catalog,node_sharedheaders toneAmber
class node_foreignkeys,node_triggers,node_types,node_ltree toneMint
class node_connection,node_plpgsql,node_fdw,node_replication,node_basebackup toneRose
```

## Components

### Query processing

- [SQL parsing](https://github.com/wanglinn/postgres/tree/master/src/backend/parser): `src/backend/parser`
- [Query rewriting](https://github.com/wanglinn/postgres/blob/master/src/backend/rewrite/rewriteHandler.c): `src/backend/rewrite/rewriteHandler.c`
- [Query planning](https://github.com/wanglinn/postgres/tree/master/src/backend/optimizer): `src/backend/optimizer`
- [Portal execution](https://github.com/wanglinn/postgres/blob/master/src/backend/tcop/pquery.c): `src/backend/tcop/pquery.c`
- [Query executor](https://github.com/wanglinn/postgres/tree/master/src/backend/executor): `src/backend/executor`
- [Query fingerprinting](https://github.com/wanglinn/postgres/blob/master/src/backend/nodes/queryjumblefuncs.c): `src/backend/nodes/queryjumblefuncs.c`

### Database engine

- [Transactions](https://github.com/wanglinn/postgres/tree/master/src/backend/access/transam): `src/backend/access/transam`
- [Heap tables](https://github.com/wanglinn/postgres/tree/master/src/backend/access/heap): `src/backend/access/heap`
- [Index access methods](https://github.com/wanglinn/postgres/tree/master/src/backend/access): `src/backend/access`
- [Relation storage](https://github.com/wanglinn/postgres/blob/master/src/backend/catalog/storage.c): `src/backend/catalog/storage.c`
- [System catalogs](https://github.com/wanglinn/postgres/tree/master/src/backend/catalog): `src/backend/catalog`
- [Core runtime interfaces](https://github.com/wanglinn/postgres/tree/master/src/include): `src/include`

### SQL capabilities

- [Foreign keys](https://github.com/wanglinn/postgres/blob/master/src/backend/commands/constraint.c): `src/backend/commands/constraint.c`
- [Triggers](https://github.com/wanglinn/postgres/blob/master/src/backend/commands/trigger.c): `src/backend/commands/trigger.c`
- [User-defined types](https://github.com/wanglinn/postgres/blob/master/src/backend/commands/typecmds.c): `src/backend/commands/typecmds.c`
- [Ltree search types](https://github.com/wanglinn/postgres/tree/master/contrib/ltree): `contrib/ltree`

### Interfaces and extensions

- [Client connections](https://github.com/wanglinn/postgres/tree/master/src/backend/libpq): `src/backend/libpq`
- [PL/pgSQL](https://github.com/wanglinn/postgres/blob/master/src/pl/plpgsql/src/pl_handler.c): `src/pl/plpgsql/src/pl_handler.c`
- [Foreign data wrapper](https://github.com/wanglinn/postgres/tree/master/contrib/postgres_fdw): `contrib/postgres_fdw`
- [Logical replication](https://github.com/wanglinn/postgres/tree/master/src/backend/replication/logical): `src/backend/replication/logical`
- [Base backups](https://github.com/wanglinn/postgres/tree/master/src/backend/backup): `src/backend/backup`

### Other components

- **SQL client**

## Connections

- SQL client → Client connections: connects
- Client connections → SQL parsing: submits SQL
- SQL parsing → Query rewriting: produces queries
- Query rewriting → Query planning: rewrites queries
- Query planning → Portal execution: plans statements
- Portal execution → Query executor: runs queries (evidence: `src/backend/tcop/pquery.c`)
- Query executor → SQL client: returns results
- Query executor → Heap tables: scans tables
- Query executor → Index access methods: uses indexes
- Query executor → Transactions: runs in
- Heap tables → Relation storage: uses storage
- Relation storage → Transactions: logs changes
- Query executor → Foreign keys: checks constraints
- Query executor → Triggers: fires triggers
- SQL parsing → User-defined types: resolves types
- Query executor → PL/pgSQL: calls functions
- Query executor → Foreign data wrapper: dispatches scans
- Transactions → Logical replication: supports changes
- Relation storage → Base backups: supplies files
- Query fingerprinting → Query executor: identifies queries
- SQL parsing → Ltree search types: exposes type syntax
- Core runtime interfaces → Relation storage: declares interfaces (evidence: `src/include/catalog/storage.h`)
- System catalogs → User-defined types: records definitions
