cli-backup 0.1.0__py3-none-any.whl

cli_backup/__init__.py

@@ -0,0 +1 @@
+"""Backup CLI."""

cli_backup/cli.py

@@ -0,0 +1,209 @@
+"""Command-line entry point for backup and recovery."""
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .config import load_config, read_project_env, resolve
+from .cpu_priority import lower_cpu_priority, validate_cpu_nice
+from .files import capture_directory, extract_archive
+from .mysql import MySQLConfig, capture_mysql, count_mysql_objects, restore_mysql
+from .redis_backup import capture_redis
+from .rehearsal import rehearse_mysql, rehearse_redis
+from .storage import LocalStorage, S3Storage, local_get, make_manifest, prune_local, s3_get, s3_list, write_private_copy
+
+
+def parser_build() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog='cli-backup')
+    parser.add_argument('--project-env', type=Path)
+    parser.add_argument('--project')
+    parser.add_argument('--local-root')
+    parser.add_argument('--temp-root')
+    parser.add_argument('--s3-bucket')
+    parser.add_argument('--s3-endpoint')
+    parser.add_argument('--s3-region')
+    parser.add_argument('--s3-prefix')
+    parser.add_argument('--compose-env-file', action='append', default=[])
+    for option in ('db-mode', 'db-name', 'db-user', 'db-host', 'db-port', 'db-service',
+                   'db-network', 'db-image', 'db-client', 'compose-dir', 'redis-host',
+                   'redis-port', 'redis-timeout', 'local-days', 'cpu-nice', 'test-mysql-image', 'test-redis-image', 'test-redis-server', 'restore-timeout'):
+        parser.add_argument('--' + option)
+    sub = parser.add_subparsers(dest='command', required=True)
+    sub.add_parser('scheduled', help='scheduled database backups; run cli-backup scheduled --help')
+    sub.add_parser('config-check')
+    publish = sub.add_parser('publish-local')
+    publish.add_argument('source', choices=['files', 'mysql', 'redis'])
+    publish.add_argument('--file', required=True)
+    backup = sub.add_parser('backup')
+    backup.add_argument('source', choices=['files', 'mysql', 'redis'])
+    backup.add_argument('--directory', type=Path)
+    backup.add_argument('--exclude', action='append', default=[])
+    for name in ('list', 'verify', 'restore', 'restore-test', 'download'):
+        item = sub.add_parser(name)
+        item.add_argument('source', choices=['files', 'mysql', 'redis'])
+        item.add_argument('--storage', choices=['local', 's3'], default='local')
+        if name != 'list':
+            item.add_argument('--file', required=(name != 'restore-test'))
+        if name == 'download':
+            item.add_argument('--destination', type=Path, required=True)
+        if name == 'restore':
+            item.add_argument('--destination', type=Path)
+            item.add_argument('--target', help='explicit database name')
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv and argv[0] == 'scheduled':
+        from .scheduled import main as scheduled_main
+        return scheduled_main(argv[1:])
+    args = parser_build().parse_args(argv)
+    try:
+        project_env = read_project_env(args.project_env) if args.project_env else {}
+        settings = vars(args)
+        config = load_config(os.environ, project_env, settings)
+        def setting(name: str, default: str = '') -> str:
+            return resolve(name, settings.get(name), project_env, os.environ) or default
+        cpu_nice = validate_cpu_nice(setting('cpu_nice', '10'))
+        if args.command == 'backup':
+            lower_cpu_priority(cpu_nice)
+        if args.command == 'config-check':
+            print(f'Configuration valid for project {config.project}')
+            return 0
+        stores = {}
+        if config.local_root:
+            stores['local'] = LocalStorage(Path(config.local_root).expanduser())
+        if config.s3_bucket and (args.command in ('backup', 'publish-local') or args.storage == 's3'):
+            def s3_factory():
+                import boto3
+                from botocore.config import Config
+                client = boto3.client('s3', endpoint_url=setting('s3_endpoint') or None,
+                    region_name=setting('s3_region') or None, config=Config(s3={'addressing_style': 'path'}),
+                    aws_access_key_id=setting('s3_key') or None,
+                    aws_secret_access_key=setting('s3_secret') or None)
+                return S3Storage(client, config.s3_bucket, setting('s3_prefix'))
+            stores['s3'] = s3_factory
+        def mysql_config(database: str | None = None) -> MySQLConfig:
+            return MySQLConfig(mode=setting('db_mode', 'compose'), database=database or setting('db_name'),
+                user=setting('db_user'), password=setting('db_password'), host=setting('db_host', '127.0.0.1'),
+                port=int(setting('db_port', '3306')), service=setting('db_service', 'mariadb'),
+                network=setting('db_network'), image=setting('db_image'), compose_dir=setting('compose_dir', '.'),
+                client=setting('db_client', 'mariadb'), compose_env_files=tuple(args.compose_env_file), cpu_nice=cpu_nice)
+        if args.command == 'publish-local':
+            if 'local' not in stores or 's3' not in stores:
+                raise ValueError('local and S3 storage are required')
+            local = stores['local']
+            manifest = next((item for item in local.list(config.project, args.source) if item.artifact == args.file), None)
+            if manifest is None or not local.verify(manifest):
+                raise ValueError('local backup missing or checksum mismatch')
+            remote = stores['s3']()
+            if not remote.verify(manifest):
+                raise ValueError('remote backup checksum mismatch')
+            remote.client.put_object(Bucket=remote.bucket, Key=remote.key(manifest) + '.json',
+                                     Body=manifest.encode(), IfNoneMatch='*')
+            print(f's3: {manifest.artifact}')
+            return 0
+        temp_root = setting('temp_root')
+        with tempfile.TemporaryDirectory(prefix='cli-backup-', dir=str(Path(temp_root).expanduser().absolute()) if temp_root else None) as tmp:
+            artifact = Path(tmp) / 'artifact'
+            if args.command == 'backup':
+                retention = setting('local_days')
+                if retention and int(retention) < 1:
+                    raise ValueError('local retention days must be positive')
+                object_counts = None
+                if args.source == 'files':
+                    if not args.directory:
+                        raise ValueError('--directory is required for file backup')
+                    capture_directory(args.directory, args.exclude, artifact)
+                elif args.source == 'mysql':
+                    database = mysql_config()
+                    object_counts = count_mysql_objects(database)
+                    with artifact.open('xb') as output:
+                        capture_mysql(database, output)
+                    if count_mysql_objects(database) != object_counts:
+                        raise ValueError('source schema object counts changed during dump')
+                else:
+                    capture_redis(artifact, setting('redis_host', '127.0.0.1'), int(setting('redis_port', '6379')), setting('redis_password') or None, timeout=int(setting('redis_timeout', '14400')))
+                if artifact.stat().st_size == 0:
+                    raise ValueError('source produced an empty backup')
+                now = datetime.now(timezone.utc)
+                name = f'{now:%Y%m%dT%H%M%SZ}-{uuid.uuid4().hex}.bin'
+                manifest = make_manifest(artifact, config.project, args.source, name, now.isoformat(), object_counts)
+                failures = []
+                for label, store in stores.items():
+                    try:
+                        destination = store() if label == 's3' else store
+                        destination.put(artifact, manifest)
+                        print(f'{label}: {name}')
+                    except Exception as exc:
+                        print(f'{label}: backup failed ({type(exc).__name__})', file=sys.stderr)
+                        failures.append(label)
+                if failures:
+                    return 1
+                if retention and 'local' in stores:
+                    removed = prune_local(stores['local'], config.project, args.source, int(retention), now)
+                    print(f'local: removed {removed} expired backups')
+                return 0
+            if args.storage not in stores:
+                raise ValueError(f'{args.storage} storage is not configured')
+            store = stores[args.storage]
+            if args.storage == 's3':
+                store = store()
+            manifests = store.list(config.project, args.source) if args.storage == 'local' else s3_list(store, config.project, args.source)
+            if args.command == 'list':
+                for item in manifests:
+                    print(f'{item.artifact}\t{item.timestamp}\t{item.size}\t{item.sha256}')
+                return 0
+            manifest = (next((item for item in manifests if item.artifact == args.file), None)
+                        if args.file else (manifests[-1] if manifests else None))
+            if manifest is None:
+                raise ValueError('backup not found')
+            with artifact.open('xb') as output:
+                (local_get if args.storage == 'local' else s3_get)(store, manifest, output)
+            if args.command == 'verify':
+                print('SHA-256 verified against downloaded bytes' if args.storage == 's3' else 'SHA-256 verified')
+            elif args.command == 'download':
+                with artifact.open('rb') as source:
+                    write_private_copy(source, args.destination)
+            elif args.command == 'restore-test':
+                if args.source == 'mysql':
+                    restored = rehearse_mysql(artifact, setting('test_mysql_image'), setting('db_client', 'mariadb'), int(setting('restore_timeout', '14400')))
+                    expected = manifest.object_counts or count_mysql_objects(mysql_config())
+                    if expected != restored:
+                        raise ValueError(f'object counts differ: expected={expected}, restored={restored}')
+                    print(f'object counts match: {restored}')
+                elif args.source == 'redis':
+                    rehearse_redis(artifact, setting('test_redis_image'), setting('test_redis_server', 'redis-server'))
+                else:
+                    raise ValueError('restore-test supports mysql and redis')
+            elif args.source == 'files':
+                if not args.destination:
+                    raise ValueError('--destination is required')
+                extract_archive(artifact, args.destination)
+                print('Extracted; original ownership is not restored', file=sys.stderr)
+            elif args.source == 'mysql':
+                if not args.target:
+                    raise ValueError('--target is required')
+                if not sys.stdin.isatty() or input(f'Restore into database {args.target}? Type yes: ') != 'yes':
+                    raise ValueError('restore not confirmed')
+                with artifact.open('rb') as source:
+                    restore_mysql(mysql_config(args.target), source)
+            else:
+                raise ValueError('live Redis restore is manual; use a verified RDB snapshot')
+            return 0
+    except (OSError, ValueError, subprocess.SubprocessError) as exc:
+        print(f'cli-backup: {exc}', file=sys.stderr)
+        return 2
+    except Exception as exc:
+        print(f'cli-backup: operation failed ({type(exc).__name__})', file=sys.stderr)
+        return 2
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

cli_backup/config.py

@@ -0,0 +1,68 @@
+"""Configuration resolution without executing project files."""
+from __future__ import annotations
+
+import os
+import re
+import shlex
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+PREFIX = "CLI_BACKUP_"
+
+
+def resolve(name: str, argument: str | None, project: Mapping[str, str], global_env: Mapping[str, str] | None = None) -> str | None:
+    key = f"{PREFIX}{name.upper()}"
+    env = os.environ if global_env is None else global_env
+    return argument if argument is not None else project.get(key, env.get(key))
+
+
+def validate_project(project: str) -> str:
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,63}", project):
+        raise ValueError("invalid project identifier")
+    return project
+
+
+def read_project_env(path: Path) -> dict[str, str]:
+    """Read literal CLI_BACKUP assignments; no expansion or shell execution."""
+    result: dict[str, str] = {}
+    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].lstrip()
+        key, sep, value = line.partition("=")
+        key = key.strip()
+        if not key.startswith(PREFIX):
+            continue
+        if not sep or not re.fullmatch(r"CLI_BACKUP_[A-Z0-9_]+", key):
+            raise ValueError(f"invalid project setting at line {number}")
+        try:
+            tokens = shlex.split(value, comments=True, posix=True)
+        except ValueError as exc:
+            raise ValueError(f"invalid project setting at line {number}") from exc
+        if len(tokens) > 1:
+            raise ValueError(f"invalid project setting at line {number}")
+        if key in result:
+            raise ValueError(f"duplicate project setting at line {number}")
+        result[key] = tokens[0] if tokens else ""
+    return result
+
+
+@dataclass(frozen=True)
+class Config:
+    project: str
+    local_root: str | None
+    s3_bucket: str | None
+
+
+def load_config(global_env: Mapping[str, str], project_env: Mapping[str, str], args: Mapping[str, str | None]) -> Config:
+    project = resolve("project", args.get("project"), project_env, global_env)
+    if not project:
+        raise ValueError("CLI_BACKUP_PROJECT is required")
+    root = resolve("local_root", args.get("local_root"), project_env, global_env) or None
+    bucket = resolve("s3_bucket", args.get("s3_bucket"), project_env, global_env) or None
+    if not root and not bucket:
+        raise ValueError("configure CLI_BACKUP_LOCAL_ROOT or CLI_BACKUP_S3_BUCKET")
+    return Config(validate_project(project), root, bucket)

cli_backup/cpu_priority.py

@@ -0,0 +1,21 @@
+"""Lower backup CPU scheduling priority without raising an inherited value."""
+from __future__ import annotations
+
+import os
+
+
+def validate_cpu_nice(value: str | int) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError('CLI_BACKUP_CPU_NICE must be an integer from 0 to 19') from exc
+    if not 0 <= parsed <= 19:
+        raise ValueError('CLI_BACKUP_CPU_NICE must be an integer from 0 to 19')
+    return parsed
+
+
+def lower_cpu_priority(value: int) -> None:
+    priority = validate_cpu_nice(value)
+    current = os.getpriority(os.PRIO_PROCESS, 0)
+    if current < priority:
+        os.setpriority(os.PRIO_PROCESS, 0, priority)

cli_backup/files.py

@@ -0,0 +1,216 @@
+"""Full directory archives and guarded POSIX extraction."""
+from __future__ import annotations
+
+import fnmatch
+import os
+import posixpath
+import shutil
+import stat
+import tarfile
+from contextlib import contextmanager
+from collections import deque
+from pathlib import Path, PurePosixPath
+from typing import Iterator, BinaryIO
+
+
+def _validate_links(links: dict[str, str]) -> None:
+    """Resolve every archive link as the kernel would, without leaving its root."""
+    for name, target in links.items():
+        if not target or target.startswith('/'):
+            raise ValueError(f'unsafe archive link: {name}')
+        parent = PurePosixPath(name).parent
+        stack = [] if str(parent) == '.' else list(parent.parts)
+        pending = deque(target.split('/'))
+        traversals = 0
+        while pending:
+            part = pending.popleft()
+            if not part or part == '.':
+                continue
+            if part == '..':
+                if not stack:
+                    raise ValueError(f'unsafe archive link: {name}')
+                stack.pop()
+                continue
+            stack.append(part)
+            candidate = '/'.join(stack)
+            if candidate in links:
+                traversals += 1
+                if traversals > 40:
+                    raise ValueError(f'cyclic archive link: {name}')
+                next_target = links[candidate]
+                if not next_target or next_target.startswith('/'):
+                    raise ValueError(f'unsafe archive link: {name}')
+                stack.pop()
+                pending.extendleft(reversed(next_target.split('/')))
+
+
+def capture_directory(path: Path, patterns: list[str], output: Path) -> None:
+    root = path.resolve(strict=True)
+    if not root.is_dir():
+        raise ValueError('source must be a directory')
+    if output.resolve().is_relative_to(root):
+        raise ValueError('archive must be outside source')
+    def excluded(name: str) -> bool:
+        return any(fnmatch.fnmatchcase(name, pattern) for pattern in patterns)
+    def walk_error(error: OSError) -> None:
+        raise error
+    # tarfile silently skips sockets: reject them and any unsupported metadata
+    # before creating an archive that our extractor could not restore.
+    source_links: dict[str, str] = {}
+    for current, directories, filenames in os.walk(root, followlinks=False, onerror=walk_error):
+        kept_dirs = []
+        for name in directories + filenames:
+            item = Path(current) / name
+            relative = item.relative_to(root).as_posix()
+            if excluded(relative):
+                continue
+            mode = item.lstat().st_mode
+            if stat.S_ISLNK(mode):
+                source_links[relative] = os.readlink(item)
+            elif not (stat.S_ISREG(mode) or stat.S_ISDIR(mode)):
+                raise ValueError(f'unsupported source file type: {relative}')
+            if name in directories:
+                kept_dirs.append(name)
+        directories[:] = kept_dirs
+    _validate_links(source_links)
+    archived_links: dict[str, str] = {}
+    def include(info: tarfile.TarInfo) -> tarfile.TarInfo | None:
+        name = info.name.removeprefix('./')
+        if excluded(name):
+            return None
+        if info.islnk():
+            # Preserve file contents without creating archive hard links.
+            info.type = tarfile.REGTYPE
+            info.size = (root / name).stat(follow_symlinks=False).st_size
+            info.linkname = ''
+        if info.issym():
+            archived_links[posixpath.normpath(name)] = info.linkname
+        elif not (info.isfile() or info.isdir()):
+            raise ValueError(f'unsupported source file type: {name}')
+        return info
+    with tarfile.open(output, 'x:gz', dereference=False) as archive:
+        archive.add(root, arcname='.', recursive=True, filter=include)
+        _validate_links(archived_links)
+
+
+@contextmanager
+def open_archive(path: Path) -> Iterator[BinaryIO]:
+    """Open an absolute regular file by no-follow descriptor traversal."""
+    text = os.fspath(path)
+    if not text.startswith('/') or text.startswith('//') or '\x00' in text or '//' in text:
+        raise ValueError('archive path must be an absolute local path')
+    parts = text.split('/')[1:]
+    if not parts or any(part in ('', '.', '..') for part in parts):
+        raise ValueError('invalid archive path')
+    if not hasattr(os, 'O_NOFOLLOW'):
+        raise ValueError('safe archive opening requires O_NOFOLLOW')
+    fd = os.open('/', os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        for part in parts[:-1]:
+            next_fd = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+            os.close(fd)
+            fd = next_fd
+        archive_fd = os.open(parts[-1], os.O_RDONLY | os.O_NOFOLLOW, dir_fd=fd)
+        try:
+            if not stat.S_ISREG(os.fstat(archive_fd).st_mode):
+                raise ValueError('archive must be a regular file')
+            with os.fdopen(archive_fd, 'rb', closefd=False) as stream:
+                yield stream
+        finally:
+            os.close(archive_fd)
+    finally:
+        os.close(fd)
+
+
+def extract_archive(artifact: Path, destination: Path) -> None:
+    """Extract into a new directory, using no-follow file descriptors throughout."""
+    if not destination.is_absolute() or destination.name in ('', '.', '..'):
+        raise ValueError('destination must be an absolute new directory')
+    with open_archive(artifact) as stream, tarfile.open(fileobj=stream, mode='r:gz') as archive:
+        members = archive.getmembers()
+        names: set[str] = set()
+        links: dict[str, str] = {}
+        for item in members:
+            raw = item.name
+            name = posixpath.normpath(raw)
+            if raw.startswith('/') or '..' in PurePosixPath(raw).parts or name == '..' or name.startswith('../') or not (item.isfile() or item.isdir() or item.issym()):
+                raise ValueError('unsafe archive member')
+            if name in names:
+                raise ValueError('duplicate archive member')
+            names.add(name)
+            if item.issym():
+                links[name] = item.linkname
+        _validate_links(links)
+        for name in names:
+            if any(str(parent) in links for parent in PurePosixPath(name).parents):
+                raise ValueError('member beneath symlink')
+
+        parent_fd = os.open('/', os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            for part in destination.parent.parts[1:]:
+                child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=parent_fd)
+                os.close(parent_fd)
+                parent_fd = child
+            os.mkdir(destination.name, 0o700, dir_fd=parent_fd)
+            root_fd = os.open(destination.name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=parent_fd)
+        finally:
+            os.close(parent_fd)
+        try:
+            def parent_for(name: str) -> tuple[int, str]:
+                parts = PurePosixPath(name).parts
+                fd = os.dup(root_fd)
+                try:
+                    for part in parts[:-1]:
+                        try:
+                            os.mkdir(part, 0o700, dir_fd=fd)
+                        except FileExistsError:
+                            pass
+                        child = os.open(part, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+                        os.close(fd)
+                        fd = child
+                    return fd, parts[-1]
+                except Exception:
+                    os.close(fd)
+                    raise
+
+            directories: list[tuple[str, int]] = []
+            for item in members:
+                name = posixpath.normpath(item.name)
+                if name == '.':
+                    if not item.isdir():
+                        raise ValueError('invalid archive root')
+                    continue
+                fd, basename = parent_for(name)
+                try:
+                    if item.isdir():
+                        try:
+                            os.mkdir(basename, 0o700, dir_fd=fd)
+                        except FileExistsError:
+                            check = os.open(basename, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+                            os.close(check)
+                        directories.append((name, item.mode & 0o777))
+                    elif item.issym():
+                        os.symlink(item.linkname, basename, dir_fd=fd)
+                    else:
+                        target = os.open(basename, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=fd)
+                        with os.fdopen(target, 'wb') as out:
+                            source = archive.extractfile(item)
+                            if source is None:
+                                raise ValueError('cannot read archive member')
+                            with source:
+                                shutil.copyfileobj(source, out)
+                            os.fchmod(out.fileno(), item.mode & 0o777)
+                finally:
+                    os.close(fd)
+            for name, mode in reversed(directories):
+                fd, basename = parent_for(name)
+                try:
+                    child = os.open(basename, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=fd)
+                    try:
+                        os.fchmod(child, mode)
+                    finally:
+                        os.close(child)
+                finally:
+                    os.close(fd)
+        finally:
+            os.close(root_fd)

cli_backup/mysql.py

@@ -0,0 +1,109 @@
+"""MariaDB/MySQL dump subprocesses."""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO
+
+_IDENTIFIER = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_$-]{0,63}\Z")
+
+
+@dataclass(frozen=True)
+class MySQLConfig:
+    mode: str
+    database: str
+    user: str
+    password: str
+    host: str = "127.0.0.1"
+    port: int = 3306
+    service: str = "mariadb"
+    network: str = ""
+    image: str = ""
+    compose_dir: str = "."
+    client: str = "mariadb"
+    compose_env_files: tuple[str, ...] = ()
+    cpu_nice: int = 10
+    container_runtime: str = "docker"
+
+    def validate(self) -> None:
+        if type(self.cpu_nice) is not int or not 0 <= self.cpu_nice <= 19:
+            raise ValueError("invalid CPU nice value")
+        if self.container_runtime not in {"docker", "podman"}:
+            raise ValueError("invalid container runtime")
+        if self.client not in {"mariadb", "mysql"}:
+            raise ValueError("invalid database client")
+        if self.mode not in {"compose", "container", "tcp", "exec"}:
+            raise ValueError("unknown connection mode")
+        if not _IDENTIFIER.fullmatch(self.database) or not self.user or self.user.startswith('-'):
+            raise ValueError("invalid database or user")
+        if not 1 <= self.port <= 65535:
+            raise ValueError("invalid port")
+        if self.mode not in ("compose", "exec") and (not self.host or self.host.startswith('-') or not re.fullmatch(r"[A-Za-z0-9_.:-]+", self.host)):
+            raise ValueError("invalid host")
+        if self.mode == "compose" and not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]*", self.service):
+            raise ValueError("invalid service")
+        if self.mode == "exec" and not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]*", self.service):
+            raise ValueError("invalid container identifier")
+        if self.mode == "container" and (not self.network or not self.image or self.network.startswith('-') or self.image.startswith('-')):
+            raise ValueError("network and image are required")
+
+
+def command(config: MySQLConfig, restore: bool = False) -> list[str]:
+    config.validate()
+    executable = config.client if restore else ("mariadb-dump" if config.client == "mariadb" else "mysqldump")
+    if config.mode == "compose":
+        prefix = [config.container_runtime, "compose"]
+        for env_file in config.compose_env_files:
+            if not env_file or env_file.startswith('-'):
+                raise ValueError("invalid Compose env file")
+            prefix.extend(["--env-file", env_file])
+        prefix.extend(["exec", "-T", "-e", "MYSQL_PWD", config.service])
+    elif config.mode == "exec":
+        prefix = [config.container_runtime, "exec", "-i", "-e", "MYSQL_PWD", config.service]
+    elif config.mode == "container":
+        prefix = [config.container_runtime, "run", "--rm", "-i", "--network", config.network, "-e", "MYSQL_PWD", config.image]
+    else:
+        prefix = []
+    args = [executable, "--user", config.user]
+    if not restore and config.mode in ("exec", "compose", "container") and config.cpu_nice:
+        args = ["nice", "-n", str(config.cpu_nice)] + args
+    if config.mode not in ("compose", "exec"):
+        args.extend(["--host", config.host, "--port", str(config.port), "--protocol", "tcp"])
+    if not restore:
+        args.extend(["--single-transaction", "--routines", "--triggers", "--events", "--hex-blob"])
+    return prefix + args + [config.database]
+
+
+def capture_mysql(config: MySQLConfig, output: BinaryIO) -> None:
+    env = dict(os.environ, MYSQL_PWD=config.password)
+    subprocess.run(command(config), cwd=config.compose_dir if config.mode == 'compose' else None,
+                   env=env, stdin=subprocess.DEVNULL, stdout=output, check=True)
+
+
+def restore_mysql(config: MySQLConfig, source: BinaryIO) -> None:
+    env = dict(os.environ, MYSQL_PWD=config.password)
+    subprocess.run(command(config, restore=True), cwd=config.compose_dir if config.mode == 'compose' else None,
+                   env=env, stdin=source, check=True)
+
+
+OBJECT_COUNTS_SQL = (
+    "SELECT (SELECT COUNT(*) FROM information_schema.TABLES WHERE TABLE_SCHEMA=DATABASE() AND TABLE_TYPE='BASE TABLE'), "
+    "(SELECT COUNT(*) FROM information_schema.VIEWS WHERE TABLE_SCHEMA=DATABASE()), "
+    "(SELECT COUNT(*) FROM information_schema.ROUTINES WHERE ROUTINE_SCHEMA=DATABASE()), "
+    "(SELECT COUNT(*) FROM information_schema.TRIGGERS WHERE TRIGGER_SCHEMA=DATABASE()), "
+    "(SELECT COUNT(*) FROM information_schema.EVENTS WHERE EVENT_SCHEMA=DATABASE())"
+)
+
+
+def count_mysql_objects(config: MySQLConfig) -> str:
+    env = dict(os.environ, MYSQL_PWD=config.password)
+    result = subprocess.run(command(config, restore=True) + ['-N', '-B', '-e', OBJECT_COUNTS_SQL],
+                            cwd=config.compose_dir if config.mode == 'compose' else None,
+                            env=env, stdin=subprocess.DEVNULL, capture_output=True, text=True, check=True)
+    count = result.stdout.strip()
+    if not re.fullmatch(r'\d+(?:\s+\d+){4}', count):
+        raise ValueError('invalid object counts from source database')
+    return count

cli_backup/redis_backup.py

@@ -0,0 +1,24 @@
+"""Redis RDB capture via the official redis-cli replication client."""
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+
+def capture_redis(output: Path, host: str, port: int, password: str | None = None, *, timeout: int = 14400) -> None:
+    if not host or host.startswith('-') or not 1 <= port <= 65535:
+        raise ValueError('invalid Redis address')
+    if timeout < 1:
+        raise ValueError('Redis timeout must be positive')
+    env = os.environ.copy()
+    if password is not None:
+        env['REDISCLI_AUTH'] = password
+    else:
+        env.pop('REDISCLI_AUTH', None)
+    subprocess.run(['redis-cli', '-h', host, '-p', str(port), '--rdb', str(output)], env=env,
+                   stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, check=True, timeout=timeout)
+    if not output.is_file() or output.stat().st_size == 0:
+        raise ValueError('Redis produced an empty snapshot')
+    subprocess.run(['redis-check-rdb', str(output)], stdin=subprocess.DEVNULL,
+                   stdout=subprocess.DEVNULL, check=True, timeout=timeout)