cplieger/pg-autodump repository overview

⁠pg-autodump

On-demand PostgreSQL logical-backup sidecar. Trigger it, and it writes a verified dump per database for your real backup tool to collect.

⁠What it does

pg-autodump runs pg_dump (custom format) against every database in DB_SPECS, verifies each dump with pg_restore --list, and writes it atomically into a shared volume under a per-server <host>_<port>/ subdirectory, keeping the newest DUMP_KEEP copies per database (7 by default). It delegates the heavy lifting: no compression, encryption, or off-site sync. Your backup tool (Kopia, Restic, Borg, rsync) already does those; point it at the /dumps volume.

It connects to Postgres over the network (the PostgreSQL wire protocol, not HTTP) and runs as an ordinary unprivileged user.

⁠Why this design

• Unprivileged and socket-less. Non-root, cap_drop: [ALL], read_only. A compromise reads databases through a least-privilege role; it cannot reach the host. No Docker socket, so no root-equivalent surface.
• Verify before replace. Each dump stages to a temp file, passes a non-empty and pg_restore --list (TOC) check, then atomically renames into place. The last known-good dump survives any failure.
• Bounded parallelism. DUMP_CONCURRENCY dumps databases concurrently with no per-host serialization, so the common one-server-many-DBs case is not forced serial. One knob, safe default.
• Built-in retention. Keeps the newest DUMP_KEEP timestamped dumps per database (7 by default), pruning older ones after each successful run. Set DUMP_KEEP=1 to instead keep a single stable <dbname>.dump and delegate versioning to your backup tool.
• Standard surface. POST /dump, GET /healthz. Trigger by the built-in daily timer (default), over HTTP, docker exec ... pg-autodump trigger, or run one cycle as a batch job with pg-autodump run (see One-shot mode⁠).

⁠Pull

docker pull cplieger/pg-autodump:latest

Also published to ghcr.io/cplieger/pg-autodump with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for pg-autodump. See the README for all configuration options and hardening.
services:
  pg-autodump:
    image: ghcr.io/cplieger/pg-autodump:latest
    container_name: pg-autodump
    restart: unless-stopped
    # Override with PUID/PGID in .env; defaults to 1000:1000.
    user: "${PUID:-1000}:${PGID:-1000}"  # match your host user
    stop_grace_period: 315s  # >= SHUTDOWN_TIMEOUT so an in-flight dump finishes on stop; see README

    environment:
      DB_SPECS: "mydb-host:5432:myapp:dbdumper_ro"  # space-separated host[:port]:dbname:user tuples

    ports:
      - "127.0.0.1:9847:9847"

    volumes:
      - "./secrets/.pgpass:/secrets/.pgpass:ro"  # mode 0600
      - "./dumps:/dumps"

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Contributing⁠
• Releases and changelog⁠

⁠License

Apache-2.0. See LICENSE⁠.

The image carries the license text of every bundled component under /usr/share/licenses/. The Alpine packages in the image ship no license file upstream, so their license texts are kept under licenses/ in this repository and copied in.

Third-party attributions are in THIRD_PARTY_NOTICES.md⁠.