fuelrod-backup 1.0.0

No project description provided

fuelrod-backup

Interactive PostgreSQL backup and restore CLI — Docker-aware, wizard-driven.

fuelrod-backup replaces fragile bash backup scripts with a Python CLI that gives you:

• Type-safe configuration loaded from a .backup env file
• Rich interactive wizards (database picker, schema filter, role analysis)
• Docker-aware subprocess handling — no binary pipe corruption, no env-var leakage
• Non-interactive mode for cron / CI (--no-interactive)
• pg_dump custom-format backups with optional gzip compression
• Automatic rotation of old backups

---

Installation

pip install fuelrod-backup

Or with pipx (recommended for CLI tools):

pipx install fuelrod-backup

Or inside a Poetry project:

poetry add fuelrod-backup

---

Quick start

1. Create a .backup config file

# .backup  (place next to your scripts or in the fuelrod-backup directory)
PG_USERNAME=postgres
PG_PASSWORD=secret
PG_HOST=127.0.0.1
PG_PORT=5432
SERVICE=postgres          # Docker container name
USE_DOCKER=true
BASE_DIR=/var/backups/postgres
COMPRESS_FILE=false
KEEP_DAYS=7

2. Run the interactive backup wizard

fuelrod-backup backup

3. Run the interactive restore wizard

fuelrod-backup restore

4. Non-interactive backup (for cron / CI)

fuelrod-backup backup --no-interactive

---

Commands

fuelrod-backup backup

Usage: fuelrod-backup backup [OPTIONS]

  Back up one or more PostgreSQL databases.

Options:
  --no-interactive          Skip all wizard prompts; back up all databases.
  --compress / --no-compress
                            Compress output with gzip.
  --keep-days INTEGER       Delete backups older than N days (0 = keep forever).
  --db TEXT                 Database(s) to back up (repeatable). Default: all.
  --schemas TEXT            Comma-separated schemas to include (applied to every DB).
  --config PATH             Path to .backup config file.

fuelrod-backup restore

Usage: fuelrod-backup restore [OPTIONS]

  Interactively restore a PostgreSQL database from a dump file.

Options:
  --config PATH   Path to .backup config file.

---

Restore wizard steps

1. Connection — review / override host, user, password; live connection test
2. Database folder — pick from directories under BASE_DIR
3. Backup file — sorted list with sizes; defaults to latest
4. Schema selection — parsed from dump TOC via pg_restore --list
5. Table selection — optional per-schema table filter
6. Role analysis — detect missing owners; offer: create / --no-owner / ignore
7. Restore options — full / schema-only / data-only, clean mode, parallel workers, dry-run
8. Target database — rename, drop-and-recreate, or overlay

---

Configuration reference

Key	Default	Description
PG_USERNAME	postgres	PostgreSQL role to connect as
PG_PASSWORD	(required)	Password
PG_HOST	127.0.0.1	Host (ignored in Docker mode)
PG_PORT	5432	Port (ignored in Docker mode)
SERVICE	postgres	Docker container name
USE_DOCKER	true	Use docker exec instead of direct connection
BASE_DIR	(required)	Root directory for backup files
COMPRESS_FILE	false	Gzip compress dump files
KEEP_DAYS	7	Retention in days (0 = keep forever)
PSQL_CMD	psql	Override psql binary path
PG_DUMP_CMD	pg_dump	Override pg_dump binary path
PG_RESTORE_CMD	pg_restore	Override pg_restore binary path

Environment variables take precedence over the .backup file.

---

Docker notes

When USE_DOCKER=true, fuelrod-backup runs all commands via docker exec, explicitly injecting PGPASSWORD and PGUSER as -e flags so the container's own POSTGRES_USER env var cannot override them.

TOC reads use docker cp (not docker exec -i) to avoid binary stream corruption under WSL/Docker Desktop.

---

License

GNU General Public License v3 or later — see LICENSE.