# chabid19/postgresql-backup architecture

> Architecture diagram of the GitHub repository chabid19/postgresql-backup, 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/chabid19/postgresql-backup
- Repository: https://github.com/chabid19/postgresql-backup

## Overview

This is a Node.js utility for scheduled PostgreSQL backups, gzip compression, retention cleanup, and restoration. The principal workflow is systemd-triggered execution through the CLI, which loads and validates configuration, dumps configured databases (optionally roles) into timestamped files, then removes expired backups. Manual commands also expose backup-only, cleanup-only, restore, and dry-run modes. The source excerpts show the runtime calls; systemd scheduling is documented in the README, so its unit relationship is documented rather than inferred from unsampled unit contents.

Main entry points: [`src/index.js`](https://github.com/chabid19/postgresql-backup/blob/master/src/index.js) (CLI Dispatcher), [`src/backup.js`](https://github.com/chabid19/postgresql-backup/blob/master/src/backup.js) (Backup & Gzip), [`src/restore.js`](https://github.com/chabid19/postgresql-backup/blob/master/src/restore.js) (Restore), [`src/logger.js`](https://github.com/chabid19/postgresql-backup/blob/master/src/logger.js) (Logger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Execution"]
  node_cli["CLI Dispatcher<br/>[index.js]"]
end

subgraph group_configuration["Configuration"]
  node_config["Config Loader<br/>[config.js]"]
  node_env["Env File Loader<br/>[env.js]"]
  node_logger["Logger<br/>[logger.js]"]
end

subgraph group_operations["Backup Operations"]
  node_backup["Backup &amp; Gzip<br/>[backup.js]"]
  node_cleanup["Retention Cleanup<br/>[cleanup.js]"]
  node_restore["Restore<br/>[restore.js]"]
  node_backup_store[("Backup Files")]
end

subgraph group_platform["PostgreSQL &amp; Scheduling"]
  node_systemd_timer["Systemd Timer"]
  node_systemd_service["Systemd Service"]
  node_pg_dump["pg_dump / pg_dumpall"]
  node_psql["psql"]
  node_postgres[("PostgreSQL")]
end

node_operator(("Operator"))

node_operator -->|"invokes"| node_cli
node_systemd_timer -->|"triggers"| node_systemd_service
node_systemd_service -->|"runs"| node_cli
node_cli -->|"loads"| node_config
node_config -->|"loads variables"| node_env
node_cli -->|"creates"| node_logger
node_cli -->|"dispatches"| node_backup
node_cli -->|"dispatches"| node_cleanup
node_cli -->|"dispatches"| node_restore
node_backup -->|"formats timestamp"| node_logger
node_backup -->|"runs dumps"| node_pg_dump
node_backup -->|"reads database"| node_postgres
node_backup -->|"writes gzip files"| node_backup_store
node_cleanup -->|"reads and deletes"| node_backup_store
node_cleanup -->|"reports"| node_logger
node_restore -->|"reads dump"| node_backup_store
node_restore -->|"streams restore"| node_psql
node_restore -->|"uses PostgreSQL environment"| node_backup
node_restore -->|"reports"| node_logger
node_pg_dump -->|"queries"| node_postgres
node_psql -->|"restores into"| node_postgres

click node_cli "https://github.com/chabid19/postgresql-backup/blob/master/src/index.js"
click node_config "https://github.com/chabid19/postgresql-backup/blob/master/src/config.js"
click node_env "https://github.com/chabid19/postgresql-backup/blob/master/src/env.js"
click node_logger "https://github.com/chabid19/postgresql-backup/blob/master/src/logger.js"
click node_backup "https://github.com/chabid19/postgresql-backup/blob/master/src/backup.js"
click node_cleanup "https://github.com/chabid19/postgresql-backup/blob/master/src/cleanup.js"
click node_restore "https://github.com/chabid19/postgresql-backup/blob/master/src/restore.js"
click node_systemd_timer "https://github.com/chabid19/postgresql-backup/blob/master/systemd/postgresql-backup.timer"
click node_systemd_service "https://github.com/chabid19/postgresql-backup/blob/master/systemd/postgresql-backup.service"

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_cli toneBlue
class node_config,node_env,node_logger toneAmber
class node_backup,node_cleanup,node_restore,node_backup_store toneMint
class node_systemd_timer,node_systemd_service,node_pg_dump,node_psql,node_postgres toneRose
class node_operator toneIndigo
```

## Components

### Execution

- [CLI Dispatcher](https://github.com/chabid19/postgresql-backup/blob/master/src/index.js): `src/index.js`

### Configuration

- [Config Loader](https://github.com/chabid19/postgresql-backup/blob/master/src/config.js): `src/config.js`
- [Env File Loader](https://github.com/chabid19/postgresql-backup/blob/master/src/env.js): `src/env.js`
- [Logger](https://github.com/chabid19/postgresql-backup/blob/master/src/logger.js): `src/logger.js`

### Backup Operations

- [Backup & Gzip](https://github.com/chabid19/postgresql-backup/blob/master/src/backup.js): `src/backup.js`
- [Retention Cleanup](https://github.com/chabid19/postgresql-backup/blob/master/src/cleanup.js): `src/cleanup.js`
- [Restore](https://github.com/chabid19/postgresql-backup/blob/master/src/restore.js): `src/restore.js`
- **Backup Files**

### PostgreSQL & Scheduling

- [Systemd Timer](https://github.com/chabid19/postgresql-backup/blob/master/systemd/postgresql-backup.timer): `systemd/postgresql-backup.timer`
- [Systemd Service](https://github.com/chabid19/postgresql-backup/blob/master/systemd/postgresql-backup.service): `systemd/postgresql-backup.service`
- **pg_dump / pg_dumpall**
- **psql**
- **PostgreSQL**

### Other components

- **Operator**

## Connections

- Operator → CLI Dispatcher: invokes (evidence: `README.md`)
- Systemd Timer → Systemd Service: triggers (evidence: `README.md`)
- Systemd Service → CLI Dispatcher: runs (evidence: `README.md`)
- CLI Dispatcher → Config Loader: loads (evidence: `src/index.js`)
- Config Loader → Env File Loader: loads variables (evidence: `src/config.js`)
- CLI Dispatcher → Logger: creates (evidence: `src/index.js`)
- CLI Dispatcher → Backup & Gzip: dispatches (evidence: `src/index.js`)
- CLI Dispatcher → Retention Cleanup: dispatches (evidence: `src/index.js`)
- CLI Dispatcher → Restore: dispatches (evidence: `src/index.js`)
- Backup & Gzip → Logger: formats timestamp (evidence: `src/backup.js`)
- Backup & Gzip → pg_dump / pg_dumpall: runs dumps (evidence: `src/backup.js`)
- Backup & Gzip → PostgreSQL: reads database (evidence: `README.md`)
- Backup & Gzip → Backup Files: writes gzip files (evidence: `src/backup.js`)
- Retention Cleanup → Backup Files: reads and deletes (evidence: `src/cleanup.js`)
- Retention Cleanup → Logger: reports (evidence: `src/cleanup.js`)
- Restore → Backup Files: reads dump (evidence: `src/restore.js`)
- Restore → psql: streams restore (evidence: `src/restore.js`)
- Restore → Backup & Gzip: uses PostgreSQL environment (evidence: `src/restore.js`)
- Restore → Logger: reports (evidence: `src/restore.js`)
- pg_dump / pg_dumpall → PostgreSQL: queries (evidence: `README.md`)
- psql → PostgreSQL: restores into (evidence: `README.md`)
