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