kevinveenbirkenbach/docker-volume-backup
1
0
Fork 0
mirror of https://github.com/kevinveenbirkenbach/docker-volume-backup.git synced 2026-08-20 13:12:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(backup)!: mandatory repo-name and databases-csv, --only-files, --only-sql

Browse Source 
Two defaults could not be right. --repo-name fell back to the literal 'backup-docker-to-local' while its help promised the git repo folder name, which nothing ever derived. --databases-csv pointed inside the installed package directory, where credentials must not live; when it applied, load_databases_df read a missing file as empty and the run finished without a single dump and without an error. Both are required now, --repo-name in the restore CLI too. The file itself may still be absent - babadcb's tolerance is untouched, only the path must be named.

--everything is withdrawn. Its one effect was to ignore --images-no-stop-required, which is what leaving that list empty already does, and its branch was the default path minus the requires_stop check. No caller, no test, and help and README described it differently.

--dump-only-sql becomes --only-sql, and --only-files joins it as the opposite half: no dumps at all, every volume as files. They form a mutually exclusive group. A host that only copies files has no business holding database passwords, so --databases-csv is not required there and is never read.

The smallest valid argv turned out to be written four times across the test tree; it now lives once. Withdrawn flags are listed in one place and proven to exit 2.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-Birkenbach
2026-08-17 13:54:39 +02:00
parent f791046c02
commit df1c65ccac
21 changed files with 330 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
tests/e2e/helpers/fixtures.py
View File

@@ -24,7 +24,7 @@ def backup_run(
database_containers: list[str],
images_no_stop_required: list[str],
images_no_backup_required: list[str] | None = None,
dump_only_sql: bool = False,
only_sql: bool = False,
) -> None:
cmd = [
"baudolo",
@@ -45,8 +45,8 @@ def backup_run(
]
if images_no_backup_required:
cmd += ["--images-no-backup-required", *images_no_backup_required]
if dump_only_sql:
cmd += ["--dump-only-sql"]
if only_sql:
cmd += ["--only-sql"]
try:
run(cmd, capture=True, check=True)

29
tests/e2e/test_e2e_cli_contract_dump_only_sql.py
View File

@@ -1,29 +0,0 @@
import unittest
from .helpers import run
class TestE2ECLIContractDumpOnlySql(unittest.TestCase):
def test_help_mentions_new_flag(self) -> None:
cp = run(["baudolo", "--help"], capture=True, check=True)
out = (cp.stdout or "") + "\n" + (cp.stderr or "")
self.assertIn(
"--dump-only-sql",
out,
f"Expected '--dump-only-sql' to appear in --help output. Output:\n{out}",
)
def test_old_flag_is_rejected(self) -> None:
cp = run(["baudolo", "--dump-only"], capture=True, check=False)
self.assertEqual(
cp.returncode,
2,
f"Expected exitcode 2 for unknown args, got {cp.returncode}\n"
f"STDOUT={cp.stdout}\nSTDERR={cp.stderr}",
)
err = (cp.stderr or "") + "\n" + (cp.stdout or "")
# Argparse typically prints "unrecognized arguments"
self.assertTrue(
("unrecognized arguments" in err) or ("usage:" in err.lower()),
f"Expected argparse-style error output. Output:\n{err}",
)

33
tests/e2e/test_e2e_cli_contract_only_sql.py Normal file
View File

@@ -0,0 +1,33 @@
import unittest
from .helpers import run
WITHDRAWN_FLAGS = ["--dump-only", "--dump-only-sql", "--everything"]
class TestE2ECLIContractOnlySql(unittest.TestCase):
def test_help_mentions_the_flag(self) -> None:
cp = run(["baudolo", "--help"], capture=True, check=True)
out = (cp.stdout or "") + "\n" + (cp.stderr or "")
self.assertIn(
"--only-sql",
out,
f"Expected '--only-sql' to appear in --help output. Output:\n{out}",
)
def test_a_withdrawn_flag_is_rejected(self) -> None:
for flag in WITHDRAWN_FLAGS:
with self.subTest(flag=flag):
cp = run(["baudolo", flag], capture=True, check=False)
self.assertEqual(
cp.returncode,
2,
f"Expected exitcode 2 for unknown args, got {cp.returncode}\n"
f"STDOUT={cp.stdout}\nSTDERR={cp.stderr}",
)
err = (cp.stderr or "") + "\n" + (cp.stdout or "")
# Argparse typically prints "unrecognized arguments"
self.assertTrue(
("unrecognized arguments" in err) or ("usage:" in err.lower()),
f"Expected argparse-style error output. Output:\n{err}",
)

4
tests/e2e/test_e2e_files_no_copy.py
View File

@@ -47,7 +47,7 @@ class TestE2EFilesNoCopy(unittest.TestCase):
cls.databases_csv = f"/tmp/{cls.prefix}/databases.csv"
write_databases_csv(cls.databases_csv, [])
# dump-only-sql => non-DB volumes are STILL backed up as files
# only-sql => non-DB volumes are STILL backed up as files
backup_run(
backups_dir=cls.backups_dir,
repo_name=cls.repo_name,
@@ -55,7 +55,7 @@ class TestE2EFilesNoCopy(unittest.TestCase):
databases_csv=cls.databases_csv,
database_containers=["dummy-db"],
images_no_stop_required=["alpine:3.20"],
dump_only_sql=True,
only_sql=True,
)
cls.hash, cls.version = latest_version_dir(cls.backups_dir, cls.repo_name)

4
tests/e2e/test_e2e_mariadb_no_copy.py
View File

@@ -89,7 +89,7 @@ class TestE2EMariaDBNoCopy(unittest.TestCase):
[(cls.db_container, cls.db_name, cls.db_user, cls.db_password)],
)
# dump-only-sql => no files
# only-sql => no files
backup_run(
backups_dir=cls.backups_dir,
repo_name=cls.repo_name,
@@ -97,7 +97,7 @@ class TestE2EMariaDBNoCopy(unittest.TestCase):
databases_csv=cls.databases_csv,
database_containers=[cls.db_container],
images_no_stop_required=[MARIADB_IMAGE],
dump_only_sql=True,
only_sql=True,
)
cls.hash, cls.version = latest_version_dir(cls.backups_dir, cls.repo_name)

116
tests/e2e/test_e2e_only_files.py Normal file
View File

@@ -0,0 +1,116 @@
"""--only-files backs a database up as a file tree and asks for no credentials.
The run deliberately passes no --databases-csv at all: a host that only copies
files has no reason to hold database passwords, and requiring the file would
make the flag useless there.
"""
import unittest
from .helpers import (
POSTGRES_DATA_DIR,
POSTGRES_IMAGE,
backup_path,
cleanup_docker,
create_minimal_compose_dir,
ensure_empty_dir,
latest_version_dir,
require_docker,
run,
unique,
wait_for_postgres,
)
MARKER = "only-files-marker"
class TestE2EOnlyFiles(unittest.TestCase):
@classmethod
def setUpClass(cls) -> None:
require_docker()
cls.prefix = unique("baudolo-e2e-only-files")
cls.backups_dir = f"/tmp/{cls.prefix}/Backups"
ensure_empty_dir(cls.backups_dir)
cls.compose_dir = create_minimal_compose_dir(f"/tmp/{cls.prefix}")
cls.repo_name = cls.prefix
cls.pg_container = f"{cls.prefix}-pg"
cls.pg_volume = f"{cls.prefix}-pg-vol"
cls.containers = [cls.pg_container]
cls.volumes = [cls.pg_volume]
run(["docker", "volume", "create", cls.pg_volume])
run(
[
"docker",
"run",
"-d",
"--name",
cls.pg_container,
"-e",
"POSTGRES_PASSWORD=pgpw",
"-e",
"POSTGRES_DB=appdb",
"-e",
"POSTGRES_USER=postgres",
"-v",
f"{cls.pg_volume}:{POSTGRES_DATA_DIR}",
POSTGRES_IMAGE,
]
)
wait_for_postgres(cls.pg_container, user="postgres", timeout_s=90)
run(
[
"docker",
"exec",
cls.pg_container,
"sh",
"-lc",
f"echo '{MARKER}' > {POSTGRES_DATA_DIR}/marker.txt",
]
)
cp = run(
[
"baudolo",
"--compose-dir",
cls.compose_dir,
"--repo-name",
cls.repo_name,
"--backups-dir",
cls.backups_dir,
"--images-no-stop-required",
POSTGRES_IMAGE,
"--only-files",
],
capture=True,
check=True,
)
cls.stdout = cp.stdout or ""
cls.hash, cls.version = latest_version_dir(cls.backups_dir, cls.repo_name)
@classmethod
def tearDownClass(cls) -> None:
cleanup_docker(containers=cls.containers, volumes=cls.volumes)
def _volume_dir(self):
return backup_path(
self.backups_dir, self.repo_name, self.version, self.pg_volume
)
def test_the_database_volume_is_backed_up_as_files(self) -> None:
marker = self._volume_dir() / "files" / "marker.txt"
self.assertTrue(marker.is_file(), f"expected a file backup at {marker}")
self.assertEqual(marker.read_text(encoding="utf-8").strip(), MARKER)
def test_no_dump_is_written(self) -> None:
sql_dir = self._volume_dir() / "sql"
dumps = list(sql_dir.glob("*.sql")) if sql_dir.exists() else []
self.assertEqual(dumps, [], f"did not expect any dump, found: {dumps}")
def test_the_missing_databases_csv_is_not_reported(self) -> None:
self.assertNotIn("databases.csv", self.stdout)
if __name__ == "__main__":
unittest.main()

12
tests/e2e/test_e2e_dump_only_fallback_to_files.py → tests/e2e/test_e2e_only_sql_fallback_to_files.py
View File

@@ -16,11 +16,11 @@ from .helpers import (
)
class TestE2EDumpOnlyFallbackToFiles(unittest.TestCase):
class TestE2EOnlySqlFallbackToFiles(unittest.TestCase):
@classmethod
def setUpClass(cls) -> None:
require_docker()
cls.prefix = unique("baudolo-e2e-dump-only-sql-fallback")
cls.prefix = unique("baudolo-e2e-only-sql-fallback")
cls.backups_dir = f"/tmp/{cls.prefix}/Backups"
ensure_empty_dir(cls.backups_dir)
@@ -57,7 +57,7 @@ class TestE2EDumpOnlyFallbackToFiles(unittest.TestCase):
wait_for_postgres(cls.pg_container, user="postgres", timeout_s=90)
# Add a deterministic marker file into the volume
cls.marker = "dump-only-sql-fallback-marker"
cls.marker = "only-sql-fallback-marker"
run(
[
"docker",
@@ -73,7 +73,7 @@ class TestE2EDumpOnlyFallbackToFiles(unittest.TestCase):
cls.databases_csv = f"/tmp/{cls.prefix}/databases.csv"
write_databases_csv(cls.databases_csv, []) # empty except header
# Run baudolo with --dump-only-sql and a DB container present:
# Run baudolo with --only-sql and a DB container present:
# Expected: WARNING + FALLBACK to file backup (files/ must exist)
cmd = [
"baudolo",
@@ -91,7 +91,7 @@ class TestE2EDumpOnlyFallbackToFiles(unittest.TestCase):
cls.pg_container,
"--images-no-stop-required",
POSTGRES_IMAGE,
"--dump-only-sql",
"--only-sql",
]
cp = run(cmd, capture=True, check=True)
@@ -122,7 +122,7 @@ class TestE2EDumpOnlyFallbackToFiles(unittest.TestCase):
def test_warns_about_missing_dump_in_dump_only_mode(self) -> None:
self.assertIn(
"WARNING: dump-only-sql requested but no DB dump was produced",
"WARNING: only-sql requested but no DB dump was produced",
self.stdout,
f"Expected warning in baudolo output. STDOUT:\n{self.stdout}",
)

10
tests/e2e/test_e2e_dump_only_sql_mixed_run.py → tests/e2e/test_e2e_only_sql_mixed_run.py
View File

@@ -16,11 +16,11 @@ from .helpers import (
)
class TestE2EDumpOnlySqlMixedRun(unittest.TestCase):
class TestE2EOnlySqlMixedRun(unittest.TestCase):
@classmethod
def setUpClass(cls) -> None:
require_docker()
cls.prefix = unique("baudolo-e2e-dump-only-sql-mixed-run")
cls.prefix = unique("baudolo-e2e-only-sql-mixed-run")
cls.backups_dir = f"/tmp/{cls.prefix}/Backups"
ensure_empty_dir(cls.backups_dir)
@@ -123,7 +123,7 @@ class TestE2EDumpOnlySqlMixedRun(unittest.TestCase):
cls.pg_container,
"--images-no-stop-required",
POSTGRES_IMAGE,
"--dump-only-sql",
"--only-sql",
"--backups-dir",
cls.backups_dir,
"--repo-name",
@@ -170,8 +170,8 @@ class TestE2EDumpOnlySqlMixedRun(unittest.TestCase):
f"Expected files dir for non-DB volume at: {files}",
)
def test_dump_only_sql_does_not_disable_non_db_files_backup(self) -> None:
# Regression guard: even with --dump-only-sql, non-DB volumes must still be backed up as files
def test_only_sql_does_not_disable_non_db_files_backup(self) -> None:
# Regression guard: even with --only-sql, non-DB volumes must still be backed up as files
base = backup_path(
self.backups_dir, self.repo_name, self.version, self.files_volume
)

2
tests/e2e/test_e2e_postgres_no_copy.py
View File

@@ -76,7 +76,7 @@ class TestE2EPostgresNoCopy(unittest.TestCase):
databases_csv=cls.databases_csv,
database_containers=[cls.pg_container],
images_no_stop_required=[POSTGRES_IMAGE],
dump_only_sql=True,
only_sql=True,
)
cls.hash, cls.version = latest_version_dir(cls.backups_dir, cls.repo_name)

5
tests/e2e/test_e2e_seed_star_and_db_entries_backup_postgres.py
View File

@@ -157,7 +157,6 @@ class TestE2ESeedStarAndDbEntriesBackupPostgres(unittest.TestCase):
]
)
# --- Run baudolo with dump-only-sql ---
cmd = [
"baudolo",
"--compose-dir",
@@ -168,7 +167,7 @@ class TestE2ESeedStarAndDbEntriesBackupPostgres(unittest.TestCase):
cls.pg_container,
"--images-no-stop-required",
POSTGRES_IMAGE,
"--dump-only-sql",
"--only-sql",
"--backups-dir",
cls.backups_dir,
"--repo-name",
@@ -194,7 +193,7 @@ class TestE2ESeedStarAndDbEntriesBackupPostgres(unittest.TestCase):
self.assertTrue(sql_dir.exists(), f"Expected sql dir at: {sql_dir}")
self.assertFalse(
files_dir.exists(),
f"Did not expect files dir for DB volume when dump-only-sql succeeded: {files_dir}",
f"Did not expect files dir for DB volume when only-sql succeeded: {files_dir}",
)
# Cluster dump file produced by '*' entry

10
tests/unit/backup/__init__.py
View File

@@ -0,0 +1,10 @@
"""The smallest argv the backup CLI accepts, shared by every test that drives it."""
REQUIRED_PAIRS = [
("--compose-dir", "/compose"),
("--backups-dir", "/backups"),
("--repo-name", "stack"),
("--databases-csv", "/etc/baudolo/databases.csv"),
]
REQUIRED = [arg for pair in REQUIRED_PAIRS for arg in pair]
BASE_ARGV = ["baudolo", *REQUIRED]

65
tests/unit/backup/test_app_only_files.py Normal file
View File

@@ -0,0 +1,65 @@
"""Contract of --only-files: no dump is attempted, every volume is copied."""
from __future__ import annotations
import unittest
from unittest import mock
from baudolo.backup import app
from baudolo.backup.volume import Backing
from . import REQUIRED_PAIRS
ARGV_WITHOUT_CSV = [
"baudolo",
*[arg for pair in REQUIRED_PAIRS if pair[0] != "--databases-csv" for arg in pair],
"--only-files",
]
def drive(argv: list[str]) -> tuple[list[str], list, list]:
backed_up: list[str] = []
def record_backup(versions_dir, volume_name, volume_dir, *, authoritative, source):
backed_up.append(volume_name)
with (
mock.patch("sys.argv", argv),
mock.patch.object(app, "get_machine_id", return_value="machine"),
mock.patch.object(app, "create_version_directory", return_value="/gen"),
mock.patch.object(app, "create_volume_directory", return_value="/gen/vol"),
mock.patch.object(app, "load_databases_df") as load_csv,
mock.patch.object(app, "docker_volume_names", return_value=["pgdata"]),
mock.patch.object(app, "containers_using_volume", return_value=["db"]),
mock.patch.object(app, "volume_is_fully_ignored", return_value=False),
mock.patch.object(app, "backup_dumps_for_volume") as dumps,
mock.patch.object(app, "inspect_backing", return_value=Backing("/data")),
mock.patch.object(app, "stamp_directory"),
mock.patch.object(app, "handle_docker_compose_services"),
mock.patch.object(app.os.path, "isdir", return_value=True),
mock.patch.object(app, "backup_volume", side_effect=record_backup),
mock.patch.object(app, "filter_stoppable", return_value=[]),
mock.patch.object(app, "requires_stop", return_value=False),
mock.patch.object(app, "change_containers_status"),
):
app.main()
return backed_up, dumps.mock_calls, load_csv.mock_calls
class TestOnlyFiles(unittest.TestCase):
def test_no_dump_is_attempted(self) -> None:
_backed_up, dumps, _load_csv = drive(ARGV_WITHOUT_CSV)
self.assertEqual(dumps, [])
def test_the_databases_csv_is_never_read(self) -> None:
"""It may legitimately be absent, so reading it would abort the run."""
_backed_up, _dumps, load_csv = drive(ARGV_WITHOUT_CSV)
self.assertEqual(load_csv, [])
def test_the_volume_is_still_copied(self) -> None:
backed_up, _dumps, _load_csv = drive(ARGV_WITHOUT_CSV)
self.assertEqual(backed_up, ["pgdata"])
if __name__ == "__main__":
unittest.main()

8
tests/unit/backup/test_app_snapshot.py
View File

@@ -10,17 +10,15 @@ from baudolo.backup import snapshot as snapshot_mod
from baudolo.backup.snapshot import volume_snapshot
from baudolo.backup.volume import Backing
from . import BASE_ARGV
def stubbed_snapshot(kind: str, subject: str, tag: str):
return volume_snapshot(kind, subject, tag, run=lambda command: [])
ARGV = [
"baudolo",
"--compose-dir",
"/compose",
"--backups-dir",
"/backups",
*BASE_ARGV,
"--snapshot",
"btrfs",
"--snapshot-subject",

8
tests/unit/backup/test_app_volumes_no_backup_required.py
View File

@@ -9,12 +9,10 @@ from unittest import mock
from baudolo.backup import app
from baudolo.backup.volume import Backing
from . import BASE_ARGV
ARGV = [
"baudolo",
"--compose-dir",
"/compose",
"--backups-dir",
"/backups",
*BASE_ARGV,
"--volumes-no-backup-required",
"derived",
]

49
tests/unit/backup/test_cli.py
View File

@@ -7,7 +7,7 @@ from unittest import mock
from baudolo.backup.cli import parse_args
REQUIRED = ["--compose-dir", "/compose", "--backups-dir", "/backups"]
from . import REQUIRED, REQUIRED_PAIRS
def parse(*extra: str):
@@ -68,19 +68,42 @@ class TestSnapshotFlags(unittest.TestCase):
class TestRequiredFlags(unittest.TestCase):
def test_backups_dir_is_required(self) -> None:
with (
mock.patch("sys.argv", ["baudolo", "--compose-dir", "/compose"]),
self.assertRaises(SystemExit),
):
parse_args()
def test_no_flag_falls_back_to_a_default(self) -> None:
for omitted, _ in REQUIRED_PAIRS:
argv = [a for pair in REQUIRED_PAIRS if pair[0] != omitted for a in pair]
with (
self.subTest(omitted=omitted),
mock.patch("sys.argv", ["baudolo", *argv]),
self.assertRaises(SystemExit),
):
parse_args()
def test_compose_dir_is_required(self) -> None:
with (
mock.patch("sys.argv", ["baudolo", "--backups-dir", "/backups"]),
self.assertRaises(SystemExit),
):
parse_args()
class TestBackupScope(unittest.TestCase):
"""--only-sql and --only-files name the two halves a generation can hold."""
def test_both_halves_by_default(self) -> None:
args = parse()
self.assertFalse(args.only_sql)
self.assertFalse(args.only_files)
def test_either_half_alone_is_accepted(self) -> None:
self.assertTrue(parse("--only-sql").only_sql)
self.assertTrue(parse("--only-files").only_files)
def test_asking_for_both_halves_alone_is_rejected(self) -> None:
with self.assertRaises(SystemExit):
parse("--only-sql", "--only-files")
def test_only_files_needs_no_databases_csv(self) -> None:
argv = [
arg
for pair in REQUIRED_PAIRS
if pair[0] != "--databases-csv"
for arg in pair
]
with mock.patch("sys.argv", ["baudolo", *argv, "--only-files"]):
self.assertIsNone(parse_args().databases_csv)
if __name__ == "__main__":

25
tests/unit/backup/test_compose_hard_restart.py
View File

@@ -3,6 +3,8 @@ from __future__ import annotations
import unittest
from unittest.mock import patch
from . import BASE_ARGV
class HardRestartArgTests(unittest.TestCase):
"""The hard-restart list defaults to empty (no compose down/up); callers
@@ -16,11 +18,7 @@ class HardRestartArgTests(unittest.TestCase):
from baudolo.backup import cli
argv = [
"baudolo",
"--compose-dir",
"/tmp",
"--backups-dir",
"/tmp/backup",
*BASE_ARGV,
"--database-containers",
"postgres",
"--images-no-stop-required",
@@ -42,23 +40,6 @@ class HardRestartArgTests(unittest.TestCase):
args = self._parse(["--hard-restart-projects", "mailu", "foo"])
self.assertEqual(args.hard_restart_projects, ["mailu", "foo"])
def test_backups_dir_is_required(self) -> None:
import sys
from baudolo.backup import cli
argv = [
"baudolo",
"--compose-dir",
"/tmp",
"--database-containers",
"postgres",
"--images-no-stop-required",
"redis",
]
with patch.object(sys, "argv", argv), self.assertRaises(SystemExit):
cli.parse_args()
if __name__ == "__main__":
unittest.main(verbosity=2)

2
tests/unit/restore/test_cli_version_flag.py
View File

@@ -18,6 +18,8 @@ class TestVersionFlagReachesEveryEngine(unittest.TestCase):
"app_vol",
"hash",
"20260817000000",
"--repo-name",
"repo",
"--container",
"db",
"--db-password",