Feature request: Atomic backup mode for single snapshot for volumes + databases
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 180
- Forks
- 12
- PR merge metrics
- No merged PRs in 30d
Description
Problem
Currently, volumes and database dumps are backed up as separate restic snapshots. A volume backup produces one snapshot, and each database dump (restic backup --stdin) produces another. This was mentioned also in #106 . This means:
- A restore requires identifying and matching the correct volume snapshot with the correct database snapshot(s)
- There is no guarantee they represent the same point in time
- For applications like Nextcloud — where the data directory and database must be consistent — this creates a real risk of restoring into an inconsistent state
Proposed solution
A new environment variable ATOMIC_BACKUP (true/false, default false).
When enabled, the backup process changes from:
restic backup /volumes → snapshot 1
restic backup --stdin db1.sql → snapshot 2
restic backup --stdin db2.sql → snapshot 3
to:
docker exec db1 dump > /databases/db1/all_databases.sql (write to disk)
docker exec db2 dump > /databases/db2/mydb.sql (write to disk)
restic backup /volumes /databases → snapshot 1 (everything)
rm -rf /databases (cleanup)
The resulting snapshot contains:
/volumes/{service}/{path}/... ← volume data
/databases/{service}/all_databases.sql ← SQL dumps
A single restic restore retrieves everything needed to reconstruct the stack.
Example usage
backup:
image: ghcr.io/lawndoc/stack-back
environment:
ATOMIC_BACKUP: "true"
# ... other env vars
No changes to container labels needed — the feature is purely opt-in via the backup container's environment.
Behavior details
- Default off: When
ATOMIC_BACKUPis unset orfalse, existing behavior is fully preserved (separate snapshots,--stdinpiping). No breaking changes. - Dump to disk: In atomic mode, each database container's dump command is streamed via
docker execto a file on the backup container's filesystem under/databases/. - Single restic call: Both
/volumesand/databasesare passed to onerestic backupinvocation, producing one snapshot. - Cleanup: The
/databases/directory is removed after the backup completes (regardless of success/failure). - Error handling: If a database dump fails, the error is logged and tracked, but remaining dumps and the restic backup still run (consistent with current behavior where one DB failure doesn't block others). The process exits with a non-zero code if any step failed.
Why this matters
For any stack where application data and database state must be consistent (Nextcloud, Gitea, WordPress, etc.), atomic snapshots eliminate the gap between volume and database backups and make restores straightforward — one snapshot, one restore, guaranteed consistency.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No files or tests are named, so start by locating the backup orchestration and the existing volume and database dump paths. Compare the current separate restic calls with the proposed ATOMIC_BACKUP branch, then verify that atomic mode creates one snapshot, cleans up /databases on success or failure, and preserves the existing default behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, docker-compose, python
- Domain
- databases, devops, infrastructure
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100