1# Backup Command
2
3Manage app database backups and app volume backups.
4
5Backups are identified by app, service, and the declared resource. Domains are
6routing addresses and are never a backup identity.
7
8## Declaring backup targets
9
10A service declares its databases and volumes in the app manifest, and lists
11which of them are backed up:
12
13```toml
14[[service]]
15name = "api"
16image = "registry.example.com/shop/api:1.4.2"
17
18[[service.database]]
19name = "orders"
20type = "postgres"
21schedule = "daily"
22
23[[service.volume]]
24name = "data"
25path = "/var/lib/data"
26
27[service.backup]
28postgres = ["orders"]
29volume = ["data"]
30```
31
32A declared database or volume that the service's backup declaration does not
33reference is not a backup target.
34
35Administrative bind mounts are never backup targets. `[service.backup]` accepts
36only declared databases and volumes, and Gordon never archives an
37operator-owned host path exposed through a bind.
38
39## gordon backups
40
41Database backups are logical PostgreSQL backups made with `pg_dump`.
42
43```bash
44gordon backups <subcommand>
45```
46
47Subcommands:
48
49- `list [app]` - List stored backups, for every app or one app
50- `run <app> --service <service> --database <database>` - Run one declared
51  database backup now
52- `status` - Show stored backups plus declared targets that have no completed
53  backup yet
54
55## gordon backups volume
56
57Volume backups are best-effort filesystem archives of the app's declared
58volumes, uploaded to S3.
59
60```bash
61gordon backups volume <subcommand>
62```
63
64Subcommands:
65
66- `list [app]` - List completed volume backup archives
67- `run <app> --service <service> --volume <volume>` - Run one declared volume
68  backup now
69- `status` - Show completed archives plus current/recent in-memory job state
70
71Volume archives are not application-consistent unless the application is
72quiesced or stopped.
73
74## Selectors
75
76`--service` and the resource flag (`--database`, `--volume`) select the target:
77
78- both given: the target must exist, otherwise the command reports not found;
79- one omitted: it is only allowed when exactly one compatible target remains;
80- several candidates: the command reports the ambiguity and lists the safe
81  `service/resource` names.
82
83Nothing is ever chosen by guessing.
84
85## Examples
86
87```bash
88# Database backups
89gordon backups list
90gordon backups list shop
91gordon backups run shop --service api --database orders
92gordon backups status
93
94# Volume backups
95gordon backups volume list
96gordon backups volume list shop
97gordon backups volume run shop --service api --volume data
98gordon backups volume status
99```
100
101## Scheduling
102
103The installation backup schedule runs every declared database whose own
104`schedule` matches the firing tier, and applies retention under the app name.
105Volume declarations carry no schedule of their own: the installation volume
106backup interval runs the declared volume targets.
107
108## JSON Output
109
110Every list, run, and status command supports `--json`.
111
112```bash
113gordon backups volume list --json
114```
115
116## Required Permissions
117
118- Read operations (`list`, `status`) require `admin:status:read`.
119- `run` requires `admin:config:write`.
120
121## Related
122
123- [CLI Commands](./index.md)
124- [Backups Configuration](../config/backups.md)
125- [Apps Configuration](../config/apps.md)