[itbm]

This PR fixes bugs that could lose data or produce silently broken backups, makes the runtime more robust, adds CI, and adds a few essential features. Its commits are listed by phase below.

Phase 1: bug fixes (424d6ae)

• Empty values are treated as unset. The README's Kubernetes example sets every variable to "". Before this change:
  • DELETE_OLDER_THAN="" deleted every backup older than midnight.
  • S3_ENDPOINT="" broke every aws call.
  • ENCRYPTION_PASSWORD="" encrypted backups with an empty password.
  • SCHEDULE="" stopped the scheduler from starting.
• COMMAND_TIMEOUT now stops the backup. Previously only sh was killed, and pg_dump and aws kept running. Jobs now run in their own process group, which gets SIGTERM and then SIGKILL.
• go-cron handles SIGTERM and SIGINT. A running job is terminated cleanly, so temporary files are removed and error hooks fire. Job output is no longer lost.
• Plain SQL restores stop at the first error (RESTORE_ON_ERROR_STOP, on by default for a single database). Previously a partial restore reported success.
• Drop and create errors fail the restore. A failed DROP DATABASE now fails the job. CREATE DATABASE runs only when the database is missing. Unsupported formats are rejected before anything is dropped.
• S3_PREFIX is normalised, so an empty or slashed prefix no longer produces s3://bucket//file.
• Each run gets its own temporary directory.
• Early validation. DELETE_OLDER_THAN and PARALLEL_JOBS are checked before any work starts.
• Reproducible Go build, with go.mod and go.sum committed. common.sh now holds the validation and setup code that was duplicated in the backup and restore scripts.

Phase 2: stability (bdb91be)

• DELETE_MATCH_DATABASE=yes (opt-in) limits retention to this database's backups, named <POSTGRES_DATABASE>_<timestamp>. The default behaviour is unchanged.
• Safer retention. The backup uploaded by the current run is never deleted, a failed delete fails the backup, and the log shows how many files were deleted and kept.
• Dumps are checked before upload. Empty dumps, custom-format dumps that pg_restore --list can't read, and corrupt gzip output are all rejected.
• New CI workflow, running ShellCheck, shell tests under bash and under BusyBox sh in the built image, gofmt, go vet, go test -race and a Docker build.
• Dependabot now also covers Go modules and GitHub Actions.

Phase 3: features (b9a7780, ed92a24)

• *_FILE variables for POSTGRES_USER, POSTGRES_PASSWORD, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY and ENCRYPTION_PASSWORD, so Docker and Kubernetes secrets work.
• BACKUP_FILE=latest restores the newest backup of the database.
• Time zones. tzdata is installed, so TZ and CRON_TZ= in SCHEDULE work.
• BACKUP_ON_START=yes runs a backup when a scheduled container starts.
• Upload options: S3_STORAGE_CLASS, S3_SSE and S3_SSE_KMS_KEY_ID.
• One-off runs go through go-cron --once. Stopping the container now stops pg_dump, psql and aws, runs cleanup and error hooks, and keeps the job's exit code.

Phase 4: after rebasing onto the end-to-end suite (302c240, 6e04e9f, be716d8, c5a2f47, 8aa9d02)

This branch is rebased onto master, which now has the end-to-end suite from #35.

• Plain restores into PostgreSQL 16 and older work again (302c240, c5a2f47, 8aa9d02). pg_dump 17 and later write SET transaction_timeout = 0; into every plain dump, which those servers reject. With stop-on-error on by default, such a restore stopped at the header and restored nothing. For servers older than 17 that line is now dropped where pg_dump writes it, after its other timeout settings. Table data and function bodies are left alone.
• Empty COMPRESSION_CMD, DECOMPRESSION_CMD and AWS_CA_BUNDLE are treated as unset (be716d8).
• DELETE_MATCH_DATABASE=yes requires the timestamp (8aa9d02), so a database named app no longer deletes app_archive_… backups.
• An empty *_FILE secret is an error (8aa9d02). An empty ENCRYPTION_PASSWORD_FILE used to turn encryption off.
• 31 xfail markers removed (6e04e9f, be716d8). The suite marks 41 known bugs on master; this branch fixes 31 of them, so their tests now pass and check these fixes. The other 10 are fixed in Fix the remaining known bugs from the end-to-end suite #36, which is stacked on this PR.

Behaviour changes to note

• Plain SQL restores of a single database now fail on SQL errors. For example, restoring into a database that already has the same tables now fails. Use DROP_DATABASE=yes with CREATE_DATABASE=yes, or set RESTORE_ON_ERROR_STOP=no to keep the old behaviour. POSTGRES_DATABASE=all stays permissive by default.
• A failed DROP DATABASE or retention delete now fails the job instead of only printing a warning.

Testing

• End-to-end suite (test/e2e, run by CI for each case file): every test passes except the 10 known bugs that Fix the remaining known bugs from the end-to-end suite #36 fixes, which stay marked xfail.
• Shell tests: sh test/hooks_test.sh runs 152 tests (55 before this PR). They pass under bash, and under BusyBox sh inside the built image. I ran the Phase 1 tests against the original scripts: 17 fail there, which confirms they catch these bugs.
• Go tests: go test -race passes. The tests cover the process-group kill on timeout, the TERM trap running on shutdown, complete output capture and exit-code mapping.
• Manual end-to-end checks with postgres:18-alpine and an S3 mock, before the suite existed:
  • plain, encrypted and custom-format backups;
  • backup with an empty prefix;
  • backup using *_FILE secrets;
  • an encrypted custom restore of latest with drop, create and parallel jobs;
  • a plain restore into a non-empty database now fails with exit code 3;
  • retention with DELETE_MATCH_DATABASE kept the unrelated file and the just-uploaded backup;
  • a job blocked on a table lock is killed at COMMAND_TIMEOUT;
  • docker stop during a scheduled, initial or one-off backup terminates pg_dump and fires backup-error;
  • the one-off exit codes (0 and 2) are preserved.

Not included

These would be worth doing later:

• several databases in one run;
• streaming uploads that don't use local disk;
• authenticated encryption (the current format is AES-CBC with no MAC).

🤖 Generated with Claude Code

https://claude.ai/code/session_01CA15ULnH4kuk41vkprNUm1