Backups Configuration

Configure automatic PostgreSQL logical backups for attachment containers.

Overview

When backups are enabled, Gordon detects PostgreSQL attachments for each route and can:

Run on-demand backups via gordon backup run
Store backup artifacts on the Gordon host filesystem
Apply retention policies per schedule tier

Current scope:

PostgreSQL 17 and 18
Logical dumps (pg_dump -Fc)
Local filesystem storage

Configuration

[backups]
enabled = true
storage_dir = "~/.gordon/backups"

[backups.retention]
hourly = 24
daily = 7
weekly = 4
monthly = 12

Settings

Key	Type	Default	Description
`backups.enabled`	bool	`false`	Enables backup service wiring
`backups.storage_dir`	string	`""`	Root backup directory. If empty, defaults to `{server.data_dir}/backups`
`backups.retention.hourly`	int	`0`	Number of hourly backups to keep per DB
`backups.retention.daily`	int	`0`	Number of daily backups to keep per DB
`backups.retention.weekly`	int	`0`	Number of weekly backups to keep per DB
`backups.retention.monthly`	int	`0`	Number of monthly backups to keep per DB

Storage Layout

Backups are stored under:

<storage_dir>/<domain>/<db>/<schedule>/<timestamp>.bak

Example:

~/.gordon/backups/app.example.com/postgres/daily/20260207T110000Z.bak

Notes

Backups require PostgreSQL attachment containers to be running.
The backup command executes inside the database container using Gordon runtime APIs.
Retention applies per database and per schedule.
backups.retention.hourly, daily, weekly, and monthly set to 0 means no backups are retained for that tier (new backups are immediately eligible for cleanup). For practical defaults, set at least daily = 7.

source

1# Backups Configuration
2
3Configure automatic PostgreSQL logical backups for attachment containers.
4
5## Overview
6
7When backups are enabled, Gordon detects PostgreSQL attachments for each route and can:
8
9- Run on-demand backups via `gordon backup run`
10- Store backup artifacts on the Gordon host filesystem
11- Apply retention policies per schedule tier
12
13Current scope:
14
15- PostgreSQL 17 and 18
16- Logical dumps (`pg_dump -Fc`)
17- Local filesystem storage
18
19## Configuration
20
21```toml
22[backups]
23enabled = true
24storage_dir = "~/.gordon/backups"
25
26[backups.retention]
27hourly = 24
28daily = 7
29weekly = 4
30monthly = 12
31```
32
33## Settings
34
35| Key | Type | Default | Description |
36|-----|------|---------|-------------|
37| `backups.enabled` | bool | `false` | Enables backup service wiring |
38| `backups.storage_dir` | string | `""` | Root backup directory. If empty, defaults to `{server.data_dir}/backups` |
39| `backups.retention.hourly` | int | `0` | Number of hourly backups to keep per DB |
40| `backups.retention.daily` | int | `0` | Number of daily backups to keep per DB |
41| `backups.retention.weekly` | int | `0` | Number of weekly backups to keep per DB |
42| `backups.retention.monthly` | int | `0` | Number of monthly backups to keep per DB |
43
44## Storage Layout
45
46Backups are stored under:
47
48```text
49<storage_dir>/<domain>/<db>/<schedule>/<timestamp>.bak
50```
51
52Example:
53
54```text
55~/.gordon/backups/app.example.com/postgres/daily/20260207T110000Z.bak
56```
57
58## Notes
59
60- Backups require PostgreSQL attachment containers to be running.
61- The backup command executes inside the database container using Gordon runtime APIs.
62- Retention applies per database and per schedule.
63- `backups.retention.hourly`, `daily`, `weekly`, and `monthly` set to `0` means no backups are retained for that tier (new backups are immediately eligible for cleanup). For practical defaults, set at least `daily = 7`.
64
65## Related
66
67- [Attachments Configuration](./attachments.md)
68- [CLI Backup Command](../cli/backup.md)
69- [Configuration Reference](./reference.md)

backups.md RawHistoryFolder