cplieger/pg-autodump repository overview

⁠pg-autodump

pg-autodump writes a checked backup file of each of your PostgreSQL databases into a folder that your backup tool already collects. It leaves encryption and off-site copies to that tool, such as Kopia, Restic, Borg or rsync.

⁠What it does

pg-autodump keeps a fresh, readable dump of every database you list, ready for your backup tool to pick up.

• Dumps each database with PostgreSQL's own pg_dump every 24 hours, or whenever you ask.
• Replaces a dump only after pg_restore can read the new one, so a failed run keeps the last good file.
• Keeps the 7 newest dumps of each database and deletes older ones.
• Shows a failed backup as an unhealthy container until every database dumps cleanly again.

⁠Who it is for

pg-autodump is built for self-hosters who run PostgreSQL behind apps such as Authentik, Paperless or Immich and already back up a folder. It connects over the network as a read-only role and needs no root and no Docker socket. It dumps the databases you list, one file each, without roles or other server-wide settings.

You need a PostgreSQL server from version 9.2 to 18 that the container can reach, and a role allowed to read every table.

One other tool suits a different need. Consider pgBackRest⁠ if you want full, differential and incremental backups of a whole server, which it can store in S3, Azure or GCS.

pg-autodump is free software under the Apache-2.0 license.

⁠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
    # Run "mkdir secrets dumps". Once secrets/.pgpass exists, run "sudo chown 1000:1000 secrets/.pgpass dumps",
    # or every dump fails. If .env sets PUID and PGID, use those numbers.
    user: "${PUID:-1000}:${PGID:-1000}"
    stop_grace_period: 320s  # SHUTDOWN_TIMEOUT (default 315s) plus the 5s cancel budget, so a dump finishes or unwinds on stop

    environment:
      # First create a login role with pg_read_all_data and CONNECT on each database.
      # The README quick start has the SQL.
      DB_SPECS: "mydb-host:5432:myapp:dbdumper_ro"  # host:port:database:role, space-separated, never localhost

    ports:
      - "127.0.0.1:9847:9847"  # POST /dump starts a backup, so keep it on loopback or set AUTH_TOKEN

    volumes:
      # Put one "host:port:database:role:password" line per database in secrets/.pgpass,
      # then run "chmod 600 secrets/.pgpass", or libpq ignores it.
      - "./secrets/.pgpass:/secrets/.pgpass:ro"
      - "./dumps:/dumps"  # point your backup tool at this folder

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Configuration⁠
• Security⁠
• How it works⁠
• Monitoring and alerts⁠
• 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⁠.