Release version 1.7.1

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -1,3 +1,26 @@
+## [1.7.1] - 2026-05-26
+
+* 🔌 MariaDB SQL backups now connect over TCP loopback so the dump always matches the same wildcard-host grant the application uses — no more surprise `ERROR 1045 Access denied` when a localhost-bound auth row preempts.
+* 🧪 New regression and bug-repro tests pin the TCP behaviour and prove it under the exact preemption setup that caused the production failure on MariaDB 12.
+* 🩺 E2E test infrastructure: DinD bridge and inner daemon now default to MTU 1280 so registry pulls survive host paths with broken PMTUD (override via `E2E_DIND_MTU`).
+
+
+## [1.7.0] - 2026-02-07
+
+* 🚀 Backup jobs now support all valid Docker Compose file names – case-insensitive and hassle-free.
+
+
+## [1.6.0] - 2026-02-06
+
+* Compose handling is now fully delegated to the Infinito.Nexus compose wrapper or plain docker compose, removing all custom env and file detection to ensure a single, consistent source of truth.
+
+
+## [1.5.0] - 2026-01-31
+
+* * Make `databases.csv` optional: missing or empty files now emit warnings and no longer break backups
+* Fix Docker CLI compatibility by switching to `docker-ce-cli` and required build tools
+
+
 ## [1.4.0] - 2026-01-31
 
 * Baudolo now restarts Docker Compose stacks in a wrapper-aware way (with a `docker compose` fallback), ensuring that all Compose overrides and env files are applied identically to the Infinito.Nexus workflow.

Dockerfile

@@ -3,32 +3,35 @@ FROM python:3.11-slim
 
 WORKDIR /app
 
-# Runtime + build essentials:
-# - rsync: required for file backup/restore
-# - ca-certificates: TLS
-# - docker-cli: needed if you want to control the host Docker engine (via /var/run/docker.sock mount)
-# - make: to delegate install logic to Makefile
-#
-# Notes:
-# - On Debian slim, the docker client package is typically "docker.io".
-# - If you only want restore-without-docker, you can drop docker.io later.
+# Base deps for build/runtime + docker repo key
 RUN apt-get update && apt-get install -y --no-install-recommends \
     make \
     rsync \
     ca-certificates \
-    docker-cli \
+    bash \
+    curl \
+    gnupg \
   && rm -rf /var/lib/apt/lists/*
 
+# Install Docker CLI (docker-ce-cli) from Docker's official apt repo
+RUN bash -lc "set -euo pipefail \
+  && install -m 0755 -d /etc/apt/keyrings \
+  && curl -fsSL https://download.docker.com/linux/debian/gpg \
+     | gpg --dearmor -o /etc/apt/keyrings/docker.gpg \
+  && chmod a+r /etc/apt/keyrings/docker.gpg \
+  && . /etc/os-release \
+  && echo \"deb [arch=\$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \${VERSION_CODENAME} stable\" \
+     > /etc/apt/sources.list.d/docker.list \
+  && apt-get update \
+  && apt-get install -y --no-install-recommends docker-ce-cli \
+  && rm -rf /var/lib/apt/lists/*"
+
 # Fail fast if docker client is missing
+RUN docker version || true
 RUN command -v docker
 
 COPY . .
-
-# All install decisions are handled by the Makefile.
 RUN make install
 
-# Sensible defaults (can be overridden at runtime)
 ENV PYTHONUNBUFFERED=1
-
-# Default: show CLI help
 CMD ["baudolo", "--help"]

Makefile

@@ -49,9 +49,9 @@ test: test-unit test-integration test-e2e
 test-unit: clean build
 	@echo ">> Running unit tests"
 	@docker run --rm -t $(IMAGE) \
-	  sh -lc 'python -m unittest discover -t . -s tests/unit -p "test_*.py" -v'
+	  bash -lc 'python -m unittest discover -t . -s tests/unit -p "test_*.py" -v'
 
 test-integration: clean build
 	@echo ">> Running integration tests"
 	@docker run --rm -t $(IMAGE) \
-	  sh -lc 'python -m unittest discover -t . -s tests/integration -p "test_*.py" -v'
+	  bash -lc 'python -m unittest discover -t . -s tests/integration -p "test_*.py" -v'

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "backup-docker-to-local"
-version = "1.4.0"
+version = "1.7.1"
 description = "Backup Docker volumes to local with rsync and optional DB dumps."
 readme = "README.md"
 requires-python = ">=3.9"

scripts/test-e2e.sh

@@ -25,6 +25,8 @@ RSYNC_IMG="${E2E_RSYNC_IMAGE:-ghcr.io/kevinveenbirkenbach/alpine-rsync}"
 READY_TIMEOUT_SECONDS="${E2E_READY_TIMEOUT_SECONDS:-120}"
 ARTIFACTS_DIR="${E2E_ARTIFACTS_DIR:-./artifacts}"
 
+DIND_MTU="${E2E_DIND_MTU:-1280}"
+
 KEEP_ON_FAIL="${E2E_KEEP_ON_FAIL:-0}"
 KEEP_VOLUMES="${E2E_KEEP_VOLUMES:-0}"
 DEBUG_SHELL="${E2E_DEBUG_SHELL:-0}"
@@ -83,7 +85,7 @@ dump_debug() {
   docker -H "${DIND_HOST}" run --rm \
     -v "${E2E_TMP_VOL}:/tmp" \
     alpine:3.20 \
-    sh -lc 'cd /tmp && tar -czf /out.tar.gz . || true' \
+    bash -lc 'cd /tmp && tar -czf /out.tar.gz . || true' \
     >/dev/null 2>&1 || true
 
   # The above writes inside the container FS, not to host. So do it properly:
@@ -91,13 +93,13 @@ dump_debug() {
   local tmpc="baudolo-e2e-tmpdump-${TS}"
   docker -H "${DIND_HOST}" rm -f "${tmpc}" >/dev/null 2>&1 || true
   docker -H "${DIND_HOST}" create --name "${tmpc}" -v "${E2E_TMP_VOL}:/tmp" alpine:3.20 \
-    sh -lc 'cd /tmp && tar -czf /tmpdump.tar.gz . || true' >/dev/null
+    bash -lc 'cd /tmp && tar -czf /tmpdump.tar.gz . || true' >/dev/null
   docker -H "${DIND_HOST}" start -a "${tmpc}" >/dev/null 2>&1 || true
   docker -H "${DIND_HOST}" cp "${tmpc}:/tmpdump.tar.gz" "${ARTIFACTS_DIR}/e2e-tmp-${TS}.tar.gz" >/dev/null 2>&1 || true
   docker -H "${DIND_HOST}" rm -f "${tmpc}" >/dev/null 2>&1 || true
 
   log "DEBUG: artifacts written:"
-  ls -la "${ARTIFACTS_DIR}" | sed 's/^/   /' || true
+  find "${ARTIFACTS_DIR}" -maxdepth 1 -mindepth 1 -print | sed 's/^/   /' || true
 }
 
 cleanup() {
@@ -124,8 +126,11 @@ cleanup() {
 }
 trap cleanup EXIT INT TERM
 
-log "Creating network ${NET} (if missing)"
-docker network inspect "${NET}" >/dev/null 2>&1 || docker network create "${NET}" >/dev/null
+log "(Re)creating network ${NET} with MTU ${DIND_MTU}"
+docker network rm "${NET}" >/dev/null 2>&1 || true
+docker network create \
+  --opt com.docker.network.driver.mtu="${DIND_MTU}" \
+  "${NET}" >/dev/null
 
 log "Removing old ${DIND} (if any)"
 docker rm -f "${DIND}" >/dev/null 2>&1 || true
@@ -148,7 +153,8 @@ docker run -d --privileged \
   -p 2375:2375 \
   docker:dind \
   --host=tcp://0.0.0.0:2375 \
-  --tls=false >/dev/null
+  --tls=false \
+  --mtu="${DIND_MTU}" >/dev/null
 
 log "Waiting for DinD to be ready..."
 for i in $(seq 1 "${READY_TIMEOUT_SECONDS}"); do
@@ -187,7 +193,7 @@ if [ "${DEBUG_SHELL}" = "1" ]; then
     -v "${DIND_VOL}:/var/lib/docker:ro" \
     -v "${E2E_TMP_VOL}:/tmp" \
     "${IMG}" \
-    sh -lc '
+    bash -lc '
       set -e
       if [ ! -f /etc/machine-id ]; then
         mkdir -p /etc
@@ -195,7 +201,7 @@ if [ "${DEBUG_SHELL}" = "1" ]; then
       fi
       echo ">> DOCKER_HOST=${DOCKER_HOST}"
       docker ps -a || true
-      exec sh
+      exec bash
     '
   rc=$?
 else
@@ -206,7 +212,7 @@ else
     -v "${DIND_VOL}:/var/lib/docker:ro" \
     -v "${E2E_TMP_VOL}:/tmp" \
     "${IMG}" \
-    sh -lc '
+    bash -lc '
     set -euo pipefail
     set -x
     export PYTHONUNBUFFERED=1

src/baudolo/backup/app.py

@@ -2,10 +2,12 @@ from __future__ import annotations
 
 import os
 import pathlib
+import sys
 from datetime import datetime
 
 import pandas
 from dirval import create_stamp_file
+from pandas.errors import EmptyDataError
 
 from .cli import parse_args
 from .compose import handle_docker_compose_services
@@ -96,6 +98,42 @@ def backup_mariadb_or_postgres(
     return False, False
 
 
+def _empty_databases_df() -> "pandas.DataFrame":
+    """
+    Create an empty DataFrame with the expected schema for databases.csv.
+
+    This allows the backup to continue without DB dumps when the CSV is missing
+    or empty (pandas EmptyDataError).
+    """
+    return pandas.DataFrame(columns=["instance", "database", "username", "password"])
+
+
+def _load_databases_df(csv_path: str) -> "pandas.DataFrame":
+    """
+    Load databases.csv robustly.
+
+    - Missing file     -> warn, continue with empty df
+    - Empty file       -> warn, continue with empty df
+    - Valid CSV        -> return dataframe
+    """
+    try:
+        return pandas.read_csv(csv_path, sep=";", keep_default_na=False, dtype=str)
+    except FileNotFoundError:
+        print(
+            f"WARNING: databases.csv not found: {csv_path}. Continuing without database dumps.",
+            file=sys.stderr,
+            flush=True,
+        )
+        return _empty_databases_df()
+    except EmptyDataError:
+        print(
+            f"WARNING: databases.csv exists but is empty: {csv_path}. Continuing without database dumps.",
+            file=sys.stderr,
+            flush=True,
+        )
+        return _empty_databases_df()
+
+
 def _backup_dumps_for_volume(
     *,
     containers: list[str],
@@ -136,9 +174,10 @@ def main() -> int:
     # IMPORTANT:
     # - keep_default_na=False prevents empty fields from turning into NaN
     # - dtype=str keeps all columns stable for comparisons/validation
-    databases_df = pandas.read_csv(
-        args.databases_csv, sep=";", keep_default_na=False, dtype=str
-    )
+    #
+    # Robust behavior:
+    # - if the file is missing or empty, we continue without DB dumps.
+    databases_df = _load_databases_df(args.databases_csv)
 
     print("💾 Start volume backups...", flush=True)
 
@@ -168,7 +207,8 @@ def main() -> int:
             if found_db:
                 if not dumped_any:
                     print(
-                        f"WARNING: dump-only-sql requested but no DB dump was produced for DB volume '{volume_name}'. Falling back to file backup.",
+                        f"WARNING: dump-only-sql requested but no DB dump was produced for DB volume '{volume_name}'. "
+                        "Falling back to file backup.",
                         flush=True,
                     )
                     # fall through to file backup below

src/baudolo/backup/compose.py

@@ -7,85 +7,58 @@ from pathlib import Path
 from typing import List, Optional
 
 
-def _detect_env_file(project_dir: Path) -> Optional[Path]:
-    """
-    Detect Compose env file in a directory.
-    Preference (same as Infinito.Nexus wrapper):
-      1) <dir>/.env (file)
-      2) <dir>/.env/env (file)  (legacy layout)
-    """
-    c1 = project_dir / ".env"
-    if c1.is_file():
-        return c1
-
-    c2 = project_dir / ".env" / "env"
-    if c2.is_file():
-        return c2
-
-    return None
-
-
-def _detect_compose_files(project_dir: Path) -> List[Path]:
-    """
-    Detect Compose file stack in a directory (same as Infinito.Nexus wrapper).
-    Always requires docker-compose.yml.
-    Optionals:
-      - docker-compose.override.yml
-      - docker-compose.ca.override.yml
-    """
-    base = project_dir / "docker-compose.yml"
-    if not base.is_file():
-        raise FileNotFoundError(f"Missing docker-compose.yml in: {project_dir}")
-
-    files = [base]
-
-    override = project_dir / "docker-compose.override.yml"
-    if override.is_file():
-        files.append(override)
-
-    ca_override = project_dir / "docker-compose.ca.override.yml"
-    if ca_override.is_file():
-        files.append(ca_override)
-
-    return files
-
-
-def _compose_wrapper_path() -> Optional[str]:
-    """
-    Prefer the Infinito.Nexus compose wrapper if present.
-    Equivalent to: `which compose`
-    """
-    return shutil.which("compose")
-
-
 def _build_compose_cmd(project_dir: str, passthrough: List[str]) -> List[str]:
     """
     Build the compose command for this project directory.
 
-    Behavior:
-    - If `compose` wrapper exists: use it with --chdir (so it resolves -f/--env-file itself)
-    - Else: use `docker compose` and replicate wrapper's file/env detection.
+    Policy:
+    - If `compose` wrapper exists (Infinito.Nexus): use it and delegate ALL logic to it.
+    - Else: use plain `docker compose` with --chdir.
+    - NO custom compose file/env detection in this project.
     """
     pdir = Path(project_dir).resolve()
 
-    wrapper = _compose_wrapper_path()
+    wrapper = shutil.which("compose")
     if wrapper:
-        # Wrapper defaults project name to basename of --chdir.
         # "--" ensures wrapper stops parsing its own args.
         return [wrapper, "--chdir", str(pdir), "--", *passthrough]
 
-    # Fallback: pure docker compose, but mirror wrapper behavior.
-    files = _detect_compose_files(pdir)
-    env_file = _detect_env_file(pdir)
+    docker = shutil.which("docker")
+    if docker:
+        return [docker, "compose", "--chdir", str(pdir), *passthrough]
 
-    cmd: List[str] = ["docker", "compose"]
-    for f in files:
-        cmd += ["-f", str(f)]
-    if env_file:
-        cmd += ["--env-file", str(env_file)]
+    raise RuntimeError("Neither 'compose' nor 'docker' found in PATH")
 
-    cmd += passthrough
-    return cmd
+
+def _find_compose_file(project_dir: str) -> Optional[Path]:
+    """
+    Detect a compose file in `project_dir` (case-insensitive).
+
+    Supported names:
+    - compose.yml / compose.yaml
+    - docker-compose.yml / docker-compose.yaml
+    """
+    pdir = Path(project_dir)
+    if not pdir.is_dir():
+        return None
+
+    # Map lowercase filename -> actual Path (preserves original casing)
+    by_lower = {p.name.lower(): p for p in pdir.iterdir() if p.is_file()}
+
+    # Preferred order (policy decision)
+    candidates = [
+        "docker-compose.yml",
+        "docker-compose.yaml",
+        "compose.yml",
+        "compose.yaml",
+    ]
+
+    for name in candidates:
+        found = by_lower.get(name)
+        if found is not None:
+            return found
+
+    return None
 
 
 def hard_restart_docker_services(dir_path: str) -> None:
@@ -102,7 +75,8 @@ def hard_restart_docker_services(dir_path: str) -> None:
 
 
 def handle_docker_compose_services(
-    parent_directory: str, hard_restart_required: list[str]
+    parent_directory: str,
+    hard_restart_required: list[str],
 ) -> None:
     for entry in os.scandir(parent_directory):
         if not entry.is_dir():
@@ -110,11 +84,12 @@ def handle_docker_compose_services(
 
         dir_path = entry.path
         name = os.path.basename(dir_path)
-        compose_file = os.path.join(dir_path, "docker-compose.yml")
 
         print(f"Checking directory: {dir_path}", flush=True)
-        if not os.path.isfile(compose_file):
-            print("No docker-compose.yml found. Skipping.", flush=True)
+
+        compose_file = _find_compose_file(dir_path)
+        if compose_file is None:
+            print("No supported compose file found. Skipping.", flush=True)
             continue
 
         if name in hard_restart_required:

src/baudolo/backup/db.py

@@ -115,8 +115,10 @@ def backup_database(
         dump_file = os.path.join(out_dir, f"{db_name}.backup.sql")
 
         if db_type == "mariadb":
+            # Force TCP so auth matches '<user>'@'%' instead of socket -> 'localhost'.
             cmd = (
                 f"docker exec {container} /usr/bin/mariadb-dump "
+                f"-h 127.0.0.1 --protocol=tcp "
                 f"-u {user} -p{password} {db_name}"
             )
             _atomic_write_cmd(cmd, dump_file)

tests/e2e/test_e2e_mariadb_anonymous_preemption.py

@@ -0,0 +1,143 @@
+"""
+Bug-repro for: mariadb-dump fails with `ERROR 1045 Access denied for user
+'<u>'@'localhost' (using password: YES)` when only '<u>'@'%' is granted and a
+preempting ''@'localhost' user is present.
+
+The fix forces TCP loopback in baudolo.backup.db so the dump matches the
+'<u>'@'%' grant instead of the socket->localhost auth row.
+
+This file:
+- builds the exact preconditions that triggered the production failure,
+- as a NEGATIVE control, runs a socket-based mariadb-dump (== the old code path)
+  and asserts that it fails with the literal 1045 / @'localhost' error,
+- as a POSITIVE proof, calls backup_database() (where the fix lives) against
+  the same DB container and asserts the dump file is produced and contains the
+  seed data.
+
+Note: the volume-rsync stage of baudolo is intentionally NOT exercised here.
+That stage needs root on /var/lib/docker/volumes, which is provided by the
+DinD wrapper in `make test-e2e` but not by an on-host invocation. The bug we
+are verifying is in the DB-dump stage, so testing backup_database() directly
+keeps the assertion focused and the test runnable both on-host and in DinD.
+"""
+
+import os
+import tempfile
+import unittest
+
+import pandas
+
+from baudolo.backup import db as db_mod
+
+from .helpers import (
+    cleanup_docker,
+    require_docker,
+    run,
+    unique,
+    wait_for_mariadb,
+    wait_for_mariadb_sql,
+)
+
+
+class TestE2EMariaDBAnonymousPreemption(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        require_docker()
+        cls.prefix = unique("baudolo-e2e-mariadb-anon")
+        cls.db_container = f"{cls.prefix}-mariadb"
+        cls.db_volume = f"{cls.prefix}-mariadb-vol"
+        cls.containers = [cls.db_container]
+        cls.volumes = [cls.db_volume]
+
+        cls.db_name = "appdb"
+        cls.db_user = "tcponly"
+        cls.db_password = "tcponlypw"
+        cls.root_password = "rootpw"
+
+        run(["docker", "volume", "create", cls.db_volume])
+
+        # Boot WITHOUT MARIADB_USER/MARIADB_PASSWORD/MARIADB_DATABASE so the
+        # entrypoint does not auto-create '<u>'@'%'. We provision the user
+        # explicitly below to mirror the SQL path used by svc-db-mariadb.
+        run([
+            "docker", "run", "-d",
+            "--name", cls.db_container,
+            "-e", f"MARIADB_ROOT_PASSWORD={cls.root_password}",
+            "-v", f"{cls.db_volume}:/var/lib/mysql",
+            "mariadb:12.2",
+        ])
+
+        wait_for_mariadb(cls.db_container, root_password=cls.root_password, timeout_s=120)
+
+        # Provision: '<u>'@'%' (the app/backup grant) + anonymous ''@'localhost'
+        # (the preemption trigger). Mirrors the production state that produced
+        # `ERROR 1045 ... '<u>'@'localhost' (using password: YES)`.
+        bootstrap_sql = (
+            f"CREATE DATABASE {cls.db_name};"
+            f"CREATE USER '{cls.db_user}'@'%' IDENTIFIED BY '{cls.db_password}';"
+            f"GRANT ALL PRIVILEGES ON {cls.db_name}.* TO '{cls.db_user}'@'%';"
+            f"CREATE USER ''@'localhost' IDENTIFIED BY 'anonpw-not-{cls.db_password}';"
+            "FLUSH PRIVILEGES;"
+            f"CREATE TABLE {cls.db_name}.t (id INT PRIMARY KEY, v VARCHAR(50));"
+            f"INSERT INTO {cls.db_name}.t VALUES (1,'ok');"
+        )
+        run([
+            "docker", "exec", cls.db_container, "sh", "-lc",
+            f'mariadb -uroot --protocol=socket -e "{bootstrap_sql}"',
+        ])
+
+        # Sanity: '<u>' can log in over TCP (matches '%'). If THIS fails,
+        # the precondition for the fix to even apply is broken.
+        wait_for_mariadb_sql(
+            cls.db_container, user=cls.db_user, password=cls.db_password, timeout_s=60
+        )
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cleanup_docker(containers=cls.containers, volumes=cls.volumes)
+
+    def test_negative_control_socket_dump_fails_with_1045(self) -> None:
+        # Reproduces the OLD code path (no -h/--protocol). MUST fail with 1045
+        # under the configured preemption. If this ever starts passing, either
+        # the MariaDB auth semantics changed or the anonymous-user setup did
+        # not take effect — in both cases the positive test below loses its
+        # ability to discriminate "fix works" vs "bug never reproduced".
+        p = run(
+            [
+                "docker", "exec", self.db_container, "sh", "-lc",
+                f"mariadb-dump -u{self.db_user} -p{self.db_password} {self.db_name}",
+            ],
+            capture=True,
+            check=False,
+        )
+        self.assertNotEqual(p.returncode, 0, "socket-based dump unexpectedly succeeded")
+        self.assertIn("1045", (p.stderr or "") + (p.stdout or ""))
+        self.assertIn("@'localhost'", (p.stderr or "") + (p.stdout or ""))
+
+    def test_backup_database_succeeds_with_tcp_fix(self) -> None:
+        # Drives the function where the fix lives. No rsync, no privileged
+        # paths — just the dump that the negative-control proved is failing
+        # under the same preemption setup.
+        with tempfile.TemporaryDirectory() as volume_dir:
+            df = pandas.DataFrame(
+                [(self.db_container, self.db_name, self.db_user, self.db_password)],
+                columns=["instance", "database", "username", "password"],
+            )
+            produced = db_mod.backup_database(
+                container=self.db_container,
+                volume_dir=volume_dir,
+                db_type="mariadb",
+                databases_df=df,
+                database_containers=[self.db_container],
+            )
+            self.assertTrue(produced, "backup_database did not produce a dump")
+            dump_path = os.path.join(volume_dir, "sql", f"{self.db_name}.backup.sql")
+            self.assertTrue(os.path.isfile(dump_path), f"expected dump at {dump_path}")
+            with open(dump_path, "r", encoding="utf-8", errors="replace") as f:
+                content = f.read()
+            self.assertIn("INSERT INTO", content)
+            self.assertIn("'ok'", content)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

tests/unit/backup/test_app_databases_csv.py

@@ -0,0 +1,77 @@
+import io
+import os
+import tempfile
+import unittest
+from contextlib import redirect_stderr
+
+import pandas as pd
+
+# Adjust if your package name/import path differs.
+from baudolo.backup.app import _load_databases_df
+
+
+EXPECTED_COLUMNS = ["instance", "database", "username", "password"]
+
+
+class TestLoadDatabasesDf(unittest.TestCase):
+    def test_missing_csv_is_handled_with_warning_and_empty_df(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            missing_path = os.path.join(td, "does-not-exist.csv")
+
+            buf = io.StringIO()
+            with redirect_stderr(buf):
+                df = _load_databases_df(missing_path)
+
+            stderr = buf.getvalue()
+            self.assertIn("WARNING:", stderr)
+            self.assertIn("databases.csv not found", stderr)
+
+            self.assertIsInstance(df, pd.DataFrame)
+            self.assertListEqual(list(df.columns), EXPECTED_COLUMNS)
+            self.assertTrue(df.empty)
+
+    def test_empty_csv_is_handled_with_warning_and_empty_df(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            empty_path = os.path.join(td, "databases.csv")
+            # Create an empty file (0 bytes)
+            with open(empty_path, "w", encoding="utf-8") as f:
+                f.write("")
+
+            buf = io.StringIO()
+            with redirect_stderr(buf):
+                df = _load_databases_df(empty_path)
+
+            stderr = buf.getvalue()
+            self.assertIn("WARNING:", stderr)
+            self.assertIn("exists but is empty", stderr)
+
+            self.assertIsInstance(df, pd.DataFrame)
+            self.assertListEqual(list(df.columns), EXPECTED_COLUMNS)
+            self.assertTrue(df.empty)
+
+    def test_valid_csv_loads_without_warning(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            csv_path = os.path.join(td, "databases.csv")
+
+            content = "instance;database;username;password\nmyapp;*;dbuser;secret\n"
+            with open(csv_path, "w", encoding="utf-8") as f:
+                f.write(content)
+
+            buf = io.StringIO()
+            with redirect_stderr(buf):
+                df = _load_databases_df(csv_path)
+
+            stderr = buf.getvalue()
+            self.assertEqual(stderr, "")  # no warning expected
+
+            self.assertIsInstance(df, pd.DataFrame)
+            self.assertListEqual(list(df.columns), EXPECTED_COLUMNS)
+            self.assertEqual(len(df), 1)
+            self.assertEqual(df.loc[0, "instance"], "myapp")
+            self.assertEqual(df.loc[0, "database"], "*")
+            self.assertEqual(df.loc[0, "username"], "dbuser")
+            self.assertEqual(df.loc[0, "password"], "secret")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/backup/test_compose.py

@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+import shutil
+import tempfile
+import unittest
+from pathlib import Path
+from typing import List
+from unittest.mock import patch
+
+
+def _touch(p: Path) -> None:
+    p.parent.mkdir(parents=True, exist_ok=True)
+
+    # If the path already exists as a directory (e.g. ".env" created by ".env/env"),
+    # remove it so we can create a file with the same name.
+    if p.exists() and p.is_dir():
+        shutil.rmtree(p)
+
+    p.write_text("x", encoding="utf-8")
+
+
+def _setup_compose_dir(
+    tmp_path: Path,
+    name: str = "mailu",
+    *,
+    compose_name: str = "docker-compose.yml",
+    with_override: bool = False,
+    with_ca_override: bool = False,
+    env_layout: str | None = None,  # None | ".env" | ".env/env"
+) -> Path:
+    d = tmp_path / name
+    d.mkdir(parents=True, exist_ok=True)
+
+    _touch(d / compose_name)
+
+    if with_override:
+        _touch(d / "docker-compose.override.yml")
+
+    if with_ca_override:
+        _touch(d / "docker-compose.ca.override.yml")
+
+    if env_layout == ".env":
+        _touch(d / ".env")
+    elif env_layout == ".env/env":
+        _touch(d / ".env" / "env")
+
+    return d
+
+
+class TestCompose(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls) -> None:
+        from baudolo.backup import compose as mod
+
+        cls.compose_mod = mod
+
+    def test_find_compose_file_supports_all_valid_names_case_insensitive(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            tmp_path = Path(td)
+
+            variants = [
+                "compose.yml",
+                "compose.yaml",
+                "docker-compose.yml",
+                "docker-compose.yaml",
+                "docker-compose.yAml",
+            ]
+
+            for i, name in enumerate(variants):
+                d = _setup_compose_dir(
+                    tmp_path,
+                    name=f"project{i}",
+                    compose_name=name,
+                )
+                found = self.compose_mod._find_compose_file(str(d))
+                self.assertIsNotNone(found)
+                self.assertEqual(found.name, name)
+
+    def test_find_compose_file_returns_none_when_missing(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            tmp_path = Path(td)
+            d = tmp_path / "empty"
+            d.mkdir(parents=True, exist_ok=True)
+
+            found = self.compose_mod._find_compose_file(str(d))
+            self.assertIsNone(found)
+
+    def test_build_cmd_uses_wrapper_when_present(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            tmp_path = Path(td)
+            d = _setup_compose_dir(
+                tmp_path,
+                with_override=True,
+                with_ca_override=True,
+                env_layout=".env",
+            )
+
+            def fake_which(name: str):
+                if name == "compose":
+                    return "/usr/local/bin/compose"
+                return None
+
+            with patch.object(self.compose_mod.shutil, "which", fake_which):
+                cmd = self.compose_mod._build_compose_cmd(str(d), ["up", "-d"])
+
+            self.assertEqual(
+                cmd,
+                [
+                    "/usr/local/bin/compose",
+                    "--chdir",
+                    str(d.resolve()),
+                    "--",
+                    "up",
+                    "-d",
+                ],
+            )
+
+    def test_build_cmd_fallback_uses_plain_docker_compose_chdir(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            tmp_path = Path(td)
+            d = _setup_compose_dir(
+                tmp_path,
+                with_override=True,
+                with_ca_override=True,
+                env_layout=".env",
+            )
+
+            def fake_which(name: str):
+                if name == "compose":
+                    return None
+                if name == "docker":
+                    return "/usr/bin/docker"
+                return None
+
+            with patch.object(self.compose_mod.shutil, "which", fake_which):
+                cmd = self.compose_mod._build_compose_cmd(
+                    str(d), ["up", "-d", "--force-recreate"]
+                )
+
+            expected: List[str] = [
+                "/usr/bin/docker",
+                "compose",
+                "--chdir",
+                str(d.resolve()),
+                "up",
+                "-d",
+                "--force-recreate",
+            ]
+            self.assertEqual(cmd, expected)
+
+    def test_hard_restart_calls_run_twice_with_correct_cmds_wrapper(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            tmp_path = Path(td)
+            d = _setup_compose_dir(tmp_path, name="mailu", env_layout=".env")
+
+            def fake_which(name: str):
+                if name == "compose":
+                    return "/usr/local/bin/compose"
+                return None
+
+            with patch.object(self.compose_mod.shutil, "which", fake_which):
+                calls = []
+
+                def fake_run(cmd, check: bool):
+                    calls.append((cmd, check))
+                    return 0
+
+                with patch.object(self.compose_mod.subprocess, "run", fake_run):
+                    self.compose_mod.hard_restart_docker_services(str(d))
+
+            self.assertEqual(
+                calls,
+                [
+                    (
+                        [
+                            "/usr/local/bin/compose",
+                            "--chdir",
+                            str(d.resolve()),
+                            "--",
+                            "down",
+                        ],
+                        True,
+                    ),
+                    (
+                        [
+                            "/usr/local/bin/compose",
+                            "--chdir",
+                            str(d.resolve()),
+                            "--",
+                            "up",
+                            "-d",
+                        ],
+                        True,
+                    ),
+                ],
+            )
+
+    def test_hard_restart_calls_run_twice_with_correct_cmds_fallback(self) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            tmp_path = Path(td)
+            d = _setup_compose_dir(
+                tmp_path,
+                name="mailu",
+                with_override=True,
+                with_ca_override=True,
+                env_layout=".env/env",
+            )
+
+            def fake_which(name: str):
+                if name == "compose":
+                    return None
+                if name == "docker":
+                    return "/usr/bin/docker"
+                return None
+
+            with patch.object(self.compose_mod.shutil, "which", fake_which):
+                calls = []
+
+                def fake_run(cmd, check: bool):
+                    calls.append((cmd, check))
+                    return 0
+
+                with patch.object(self.compose_mod.subprocess, "run", fake_run):
+                    self.compose_mod.hard_restart_docker_services(str(d))
+
+            self.assertEqual(
+                calls,
+                [
+                    (
+                        [
+                            "/usr/bin/docker",
+                            "compose",
+                            "--chdir",
+                            str(d.resolve()),
+                            "down",
+                        ],
+                        True,
+                    ),
+                    (
+                        [
+                            "/usr/bin/docker",
+                            "compose",
+                            "--chdir",
+                            str(d.resolve()),
+                            "up",
+                            "-d",
+                        ],
+                        True,
+                    ),
+                ],
+            )
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

tests/unit/backup/test_db_mariadb_dump.py

@@ -0,0 +1,68 @@
+import tempfile
+import unittest
+from unittest.mock import patch
+
+import pandas
+
+from baudolo.backup import db as db_mod
+
+
+def _df(rows):
+    return pandas.DataFrame(
+        rows, columns=["instance", "database", "username", "password"]
+    )
+
+
+def _capture_commands(*, db_type, rows, container):
+    captured = []
+
+    def _capture(cmd):
+        captured.append(cmd)
+        return []
+
+    with tempfile.TemporaryDirectory() as td:
+        with patch.object(db_mod, "execute_shell_command", side_effect=_capture):
+            db_mod.backup_database(
+                container=container,
+                volume_dir=td,
+                db_type=db_type,
+                databases_df=_df(rows),
+                database_containers=[container],
+            )
+    return captured
+
+
+class TestMariaDBDumpUsesTCP(unittest.TestCase):
+    # Regression guard for 'Access denied for user <user>@localhost' when only
+    # '<user>'@'%' is granted: the in-container mariadb-dump MUST force TCP so
+    # the connection is auth-matched against '%' instead of socket->localhost.
+
+    def test_mariadb_dump_forces_tcp_loopback(self):
+        captured = _capture_commands(
+            db_type="mariadb",
+            rows=[("mariadb", "appdb", "appuser", "s3cret")],
+            container="mariadb",
+        )
+        dump_cmds = [c for c in captured if "mariadb-dump" in c]
+        self.assertEqual(len(dump_cmds), 1, f"expected one dump command, got: {captured}")
+
+        cmd = dump_cmds[0]
+        self.assertIn("-h 127.0.0.1", cmd)
+        self.assertIn("--protocol=tcp", cmd)
+        self.assertIn("-u appuser", cmd)
+        self.assertIn("-ps3cret", cmd)
+        self.assertIn(" appdb", cmd)
+
+    def test_postgres_dump_unaffected(self):
+        captured = _capture_commands(
+            db_type="postgres",
+            rows=[("pg", "appdb", "appuser", "s3cret")],
+            container="pg",
+        )
+        dump_cmds = [c for c in captured if "pg_dump" in c and "pg_dumpall" not in c]
+        self.assertEqual(len(dump_cmds), 1)
+        self.assertNotIn("--protocol=tcp", dump_cmds[0])
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

tests/unit/seed/test_main.py

@@ -1,4 +1,3 @@
-# tests/unit/src/baudolo/seed/test_main.py
 from __future__ import annotations
 
 import unittest
@@ -33,6 +32,30 @@ class TestSeedMain(unittest.TestCase):
         with self.assertRaises(ValueError):
             seed_main._validate_database_value("bad name", instance="x")
 
+    def _mock_df_mask_any(self, *, any_value: bool) -> MagicMock:
+        """
+        Build a DataFrame-like mock such that:
+          mask = (df["instance"] == instance) & (df["database"] == database)
+          mask.any() returns any_value
+        """
+        df = MagicMock(spec=pd.DataFrame)
+
+        left = MagicMock()
+        right = MagicMock()
+
+        mask = MagicMock()
+        mask.any.return_value = any_value
+
+        # (left & right) => mask
+        left.__and__.return_value = mask
+
+        # df["instance"] / df["database"] => return objects whose == produces left/right
+        col = MagicMock()
+        col.__eq__.side_effect = [left, right]
+        df.__getitem__.return_value = col
+
+        return df
+
     @patch("baudolo.seed.__main__.os.path.exists", return_value=False)
     @patch("baudolo.seed.__main__.pd.read_csv")
     @patch("baudolo.seed.__main__._empty_df")
@@ -44,11 +67,7 @@ class TestSeedMain(unittest.TestCase):
         read_csv: MagicMock,
         exists: MagicMock,
     ) -> None:
-        df_existing = MagicMock(spec=pd.DataFrame)
-        series_mask = MagicMock()
-        series_mask.any.return_value = False
-
-        df_existing.__getitem__.return_value = series_mask  # for df["instance"] etc.
+        df_existing = self._mock_df_mask_any(any_value=False)
         empty_df.return_value = df_existing
 
         df_out = MagicMock(spec=pd.DataFrame)
@@ -82,16 +101,7 @@ class TestSeedMain(unittest.TestCase):
         read_csv: MagicMock,
         exists: MagicMock,
     ) -> None:
-        """
-        Key regression test:
-        If file exists but is empty => warn, create header columns, then proceed.
-        """
-        df_existing = MagicMock(spec=pd.DataFrame)
-        series_mask = MagicMock()
-        series_mask.any.return_value = False
-
-        # emulate df["instance"] and df["database"] usage
-        df_existing.__getitem__.return_value = series_mask
+        df_existing = self._mock_df_mask_any(any_value=False)
         empty_df.return_value = df_existing
 
         df_out = MagicMock(spec=pd.DataFrame)
@@ -108,15 +118,23 @@ class TestSeedMain(unittest.TestCase):
         exists.assert_called_once_with("/tmp/databases.csv")
         read_csv.assert_called_once()
         empty_df.assert_called_once()
-
-        # warning was printed to stderr
-        self.assertTrue(print_.called)
-        args, kwargs = print_.call_args
-        self.assertIn("WARNING: databases.csv exists but is empty", args[0])
-        self.assertIn("file", kwargs)
-        self.assertEqual(kwargs["file"], seed_main.sys.stderr)
-
         concat.assert_called_once()
+
+        # Assert: at least one print call contains the WARNING and prints to stderr
+        warning_calls = []
+        for call in print_.call_args_list:
+            args, kwargs = call
+            if args and "WARNING: databases.csv exists but is empty" in str(args[0]):
+                warning_calls.append((args, kwargs))
+
+        self.assertTrue(
+            warning_calls,
+            "Expected a WARNING print when databases.csv is empty, but none was found.",
+        )
+        # Ensure the warning goes to stderr
+        _, warn_kwargs = warning_calls[0]
+        self.assertEqual(warn_kwargs.get("file"), seed_main.sys.stderr)
+
         df_out.to_csv.assert_called_once_with(
             "/tmp/databases.csv", sep=";", index=False
         )
@@ -128,22 +146,7 @@ class TestSeedMain(unittest.TestCase):
         read_csv: MagicMock,
         exists: MagicMock,
     ) -> None:
-        df = MagicMock(spec=pd.DataFrame)
-
-        # mask.any() => True triggers update branch
-        mask = MagicMock()
-        mask.any.return_value = True
-
-        # df["instance"] etc => return something that supports comparisons;
-        # simplest: just return an object that makes mask flow work.
-        df.__getitem__.return_value = MagicMock()
-        # Force the computed mask to be our mask
-        # by making (df["instance"] == instance) & (df["database"] == database) return `mask`
-        left = MagicMock()
-        right = MagicMock()
-        left.__and__.return_value = mask
-        df.__getitem__.return_value.__eq__.side_effect = [left, right]  # two == calls
-
+        df = self._mock_df_mask_any(any_value=True)
         read_csv.return_value = df
 
         seed_main.check_and_add_entry(
@@ -154,9 +157,6 @@ class TestSeedMain(unittest.TestCase):
             password="pass",
         )
 
-        # update branch: df.loc[mask, ["username","password"]] = ...
-        # we can't easily assert the assignment, but we can assert .loc was accessed
-        self.assertTrue(hasattr(df, "loc"))
         df.to_csv.assert_called_once_with("/tmp/databases.csv", sep=";", index=False)
 
     @patch("baudolo.seed.__main__.check_and_add_entry")
@@ -205,7 +205,6 @@ class TestSeedMain(unittest.TestCase):
 
         seed_main.main()
 
-        # prints error to stderr and exits with 1
         self.assertTrue(print_.called)
         _, kwargs = print_.call_args
         self.assertEqual(kwargs.get("file"), seed_main.sys.stderr)
@@ -213,4 +212,4 @@ class TestSeedMain(unittest.TestCase):
 
 
 if __name__ == "__main__":
-    unittest.main()
+    unittest.main(verbosity=2)

tests/unit/src/baudolo/backup/test_compose.py

@@ -1,215 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-from typing import List
-
-import pytest
-
-
-@pytest.fixture
-def compose_mod():
-    """
-    Import the module under test.
-    Adjust the import path if your package layout differs.
-    """
-    from baudolo.backup import compose as mod
-
-    return mod
-
-
-def _touch(p: Path) -> None:
-    p.parent.mkdir(parents=True, exist_ok=True)
-    p.write_text("x", encoding="utf-8")
-
-
-def _setup_compose_dir(
-    tmp_path: Path,
-    name: str = "mailu",
-    *,
-    with_override: bool = False,
-    with_ca_override: bool = False,
-    env_layout: str | None = None,  # None | ".env" | ".env/env"
-) -> Path:
-    d = tmp_path / name
-    d.mkdir(parents=True, exist_ok=True)
-
-    _touch(d / "docker-compose.yml")
-
-    if with_override:
-        _touch(d / "docker-compose.override.yml")
-
-    if with_ca_override:
-        _touch(d / "docker-compose.ca.override.yml")
-
-    if env_layout == ".env":
-        _touch(d / ".env")
-    elif env_layout == ".env/env":
-        _touch(d / ".env" / "env")
-
-    return d
-
-
-def test_detect_env_file_prefers_dotenv_over_legacy(tmp_path: Path, compose_mod):
-    d = _setup_compose_dir(tmp_path, env_layout=".env/env")
-    # Also create .env file -> should be preferred
-    _touch(d / ".env")
-
-    env_file = compose_mod._detect_env_file(d)
-    assert env_file == d / ".env"
-
-
-def test_detect_env_file_uses_legacy_if_no_dotenv(tmp_path: Path, compose_mod):
-    d = _setup_compose_dir(tmp_path, env_layout=".env/env")
-    env_file = compose_mod._detect_env_file(d)
-    assert env_file == d / ".env" / "env"
-
-
-def test_detect_compose_files_requires_base(tmp_path: Path, compose_mod):
-    d = tmp_path / "stack"
-    d.mkdir()
-
-    with pytest.raises(FileNotFoundError):
-        compose_mod._detect_compose_files(d)
-
-
-def test_detect_compose_files_includes_optional_overrides(tmp_path: Path, compose_mod):
-    d = _setup_compose_dir(
-        tmp_path,
-        with_override=True,
-        with_ca_override=True,
-    )
-
-    files = compose_mod._detect_compose_files(d)
-    assert files == [
-        d / "docker-compose.yml",
-        d / "docker-compose.override.yml",
-        d / "docker-compose.ca.override.yml",
-    ]
-
-
-def test_build_cmd_uses_wrapper_when_present(monkeypatch, tmp_path: Path, compose_mod):
-    d = _setup_compose_dir(
-        tmp_path, with_override=True, with_ca_override=True, env_layout=".env"
-    )
-
-    # Pretend "which compose" finds a wrapper.
-    monkeypatch.setattr(
-        compose_mod.shutil, "which", lambda name: "/usr/local/bin/compose"
-    )
-
-    cmd = compose_mod._build_compose_cmd(str(d), ["up", "-d"])
-
-    # Wrapper should be used, and wrapper itself resolves -f / --env-file.
-    assert cmd == [
-        "/usr/local/bin/compose",
-        "--chdir",
-        str(d.resolve()),
-        "--",
-        "up",
-        "-d",
-    ]
-
-
-def test_build_cmd_fallback_docker_compose_with_all_files_and_env(
-    monkeypatch, tmp_path: Path, compose_mod
-):
-    d = _setup_compose_dir(
-        tmp_path,
-        with_override=True,
-        with_ca_override=True,
-        env_layout=".env",
-    )
-
-    # No wrapper found.
-    monkeypatch.setattr(compose_mod.shutil, "which", lambda name: None)
-
-    cmd = compose_mod._build_compose_cmd(str(d), ["up", "-d", "--force-recreate"])
-
-    # Fallback should replicate the wrapper resolution logic.
-    expected: List[str] = [
-        "docker",
-        "compose",
-        "-f",
-        str((d / "docker-compose.yml").resolve()),
-        "-f",
-        str((d / "docker-compose.override.yml").resolve()),
-        "-f",
-        str((d / "docker-compose.ca.override.yml").resolve()),
-        "--env-file",
-        str((d / ".env").resolve()),
-        "up",
-        "-d",
-        "--force-recreate",
-    ]
-    assert cmd == expected
-
-
-def test_hard_restart_calls_run_twice_with_correct_cmds_wrapper(
-    monkeypatch, tmp_path: Path, compose_mod
-):
-    d = _setup_compose_dir(tmp_path, name="mailu", env_layout=".env")
-
-    # Wrapper exists
-    monkeypatch.setattr(
-        compose_mod.shutil, "which", lambda name: "/usr/local/bin/compose"
-    )
-
-    calls = []
-
-    def fake_run(cmd, check: bool):
-        calls.append((cmd, check))
-        return 0
-
-    monkeypatch.setattr(compose_mod.subprocess, "run", fake_run)
-
-    compose_mod.hard_restart_docker_services(str(d))
-
-    assert calls == [
-        (["/usr/local/bin/compose", "--chdir", str(d.resolve()), "--", "down"], True),
-        (
-            ["/usr/local/bin/compose", "--chdir", str(d.resolve()), "--", "up", "-d"],
-            True,
-        ),
-    ]
-
-
-def test_hard_restart_calls_run_twice_with_correct_cmds_fallback(
-    monkeypatch, tmp_path: Path, compose_mod
-):
-    d = _setup_compose_dir(
-        tmp_path,
-        name="mailu",
-        with_override=True,
-        with_ca_override=True,
-        env_layout=".env/env",
-    )
-
-    # No wrapper exists
-    monkeypatch.setattr(compose_mod.shutil, "which", lambda name: None)
-
-    calls = []
-
-    def fake_run(cmd, check: bool):
-        calls.append((cmd, check))
-        return 0
-
-    monkeypatch.setattr(compose_mod.subprocess, "run", fake_run)
-
-    compose_mod.hard_restart_docker_services(str(d))
-
-    # We assert only key structure + ordering to keep it robust.
-    down_cmd = calls[0][0]
-    up_cmd = calls[1][0]
-
-    assert calls[0][1] is True
-    assert calls[1][1] is True
-
-    # down: docker compose -f ... --env-file ... down
-    assert down_cmd[0:2] == ["docker", "compose"]
-    assert down_cmd[-1] == "down"
-    assert "--env-file" in down_cmd
-
-    # up: docker compose ... up -d
-    assert up_cmd[0:2] == ["docker", "compose"]
-    assert up_cmd[-2:] == ["up", "-d"] or up_cmd[-3:] == ["up", "-d"]  # tolerance
-    assert "--env-file" in up_cmd