# catrilao/pg_guardian architecture

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

- Interactive diagram: https://gitdiagram.com/catrilao/pg_guardian
- Repository: https://github.com/catrilao/pg_guardian

## Overview

PG Guardian is a PostgreSQL background-worker extension that periodically runs registered analyzers against the connected database and logs findings. The implemented path is currently the storage analyzer: the worker initializes its SPI plan, then runs it on a timed loop and processes matching relation names. The README lists other possible analysis areas, but the sampled tree exposes only storage analysis; those areas are not represented as implemented components. The graph reflects the available source and documented worker architecture.

Main entry points: [`src/analyzers/storage.c`](https://github.com/catrilao/pg_guardian/blob/main/src/analyzers/storage.c) (Storage analyzer), [`src/pg_guardian.c`](https://github.com/catrilao/pg_guardian/blob/main/src/pg_guardian.c) (Background worker), [`src/analyzer.c`](https://github.com/catrilao/pg_guardian/blob/main/src/analyzer.c) (Plan and execute)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Worker runtime"]
  node_worker["Background worker<br/>[pg_guardian.c]"]
  node_config["Worker configuration<br/>[pg_guardian.c]"]
end

subgraph group_framework["Analyzer framework"]
  node_plan["Plan and execute<br/>[analyzer.c]"]
end

subgraph group_storage["Storage analysis"]
  node_storage_gucs["Storage settings<br/>[storage.c]"]
  node_storage_analyzer["Storage analyzer<br/>[storage.c]"]
  node_results["Logged relation names<br/>[storage.c]"]
end

node_postgres(("PostgreSQL server"))
node_database[("Monitored database")]
node_spi["PostgreSQL SPI"]
node_catalogs[("Relation catalog")]

node_postgres -->|"loads extension"| node_worker
node_worker -->|"registers settings"| node_config
node_worker -->|"registers analyzer"| node_storage_analyzer
node_storage_analyzer -->|"registers settings"| node_storage_gucs
node_worker -->|"connects to"| node_database
node_worker -->|"initializes and schedules"| node_storage_analyzer
node_storage_analyzer -->|"initializes plan"| node_plan
node_plan -->|"prepares query"| node_spi
node_worker -->|"dispatches execution"| node_storage_analyzer
node_storage_analyzer -->|"executes plan"| node_plan
node_plan -->|"executes query"| node_spi
node_spi -->|"reads relations"| node_catalogs
node_plan -->|"passes results"| node_storage_analyzer
node_storage_analyzer -->|"logs names"| node_results

click node_worker "https://github.com/catrilao/pg_guardian/blob/main/src/pg_guardian.c"
click node_config "https://github.com/catrilao/pg_guardian/blob/main/src/pg_guardian.c"
click node_storage_gucs "https://github.com/catrilao/pg_guardian/blob/main/src/analyzers/storage.c"
click node_storage_analyzer "https://github.com/catrilao/pg_guardian/blob/main/src/analyzers/storage.c"
click node_plan "https://github.com/catrilao/pg_guardian/blob/main/src/analyzer.c"
click node_results "https://github.com/catrilao/pg_guardian/blob/main/src/analyzers/storage.c"

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_worker,node_config toneBlue
class node_plan,node_postgres,node_database,node_spi,node_catalogs toneAmber
class node_storage_gucs,node_storage_analyzer,node_results toneMint
```

## Components

### Worker runtime

- [Background worker](https://github.com/catrilao/pg_guardian/blob/main/src/pg_guardian.c): `src/pg_guardian.c`
- [Worker configuration](https://github.com/catrilao/pg_guardian/blob/main/src/pg_guardian.c): `src/pg_guardian.c`

### Analyzer framework

- [Plan and execute](https://github.com/catrilao/pg_guardian/blob/main/src/analyzer.c): `src/analyzer.c`

### Storage analysis

- [Storage settings](https://github.com/catrilao/pg_guardian/blob/main/src/analyzers/storage.c): `src/analyzers/storage.c`
- [Storage analyzer](https://github.com/catrilao/pg_guardian/blob/main/src/analyzers/storage.c): `src/analyzers/storage.c`
- [Logged relation names](https://github.com/catrilao/pg_guardian/blob/main/src/analyzers/storage.c): `src/analyzers/storage.c`

### Other components

- **PostgreSQL server**
- **Monitored database**
- **PostgreSQL SPI**
- **Relation catalog**

## Connections

- PostgreSQL server → Background worker: loads extension
- Background worker → Worker configuration: registers settings
- Background worker → Storage analyzer: registers analyzer
- Storage analyzer → Storage settings: registers settings
- Background worker → Monitored database: connects to
- Background worker → Storage analyzer: initializes and schedules
- Storage analyzer → Plan and execute: initializes plan
- Plan and execute → PostgreSQL SPI: prepares query
- Background worker → Storage analyzer: dispatches execution
- Storage analyzer → Plan and execute: executes plan
- Plan and execute → PostgreSQL SPI: executes query
- PostgreSQL SPI → Relation catalog: reads relations
- Plan and execute → Storage analyzer: passes results
- Storage analyzer → Logged relation names: logs names