ganiyevuz/postgres-backup-telegram repository overview

⁠ganiyevuz/postgres-backup-telegram

Automated PostgreSQL backups in Docker with rotating retention, Telegram notifications, optional GPG encryption, and built-in restore tooling.

Supports multiple databases, cluster-wide dumps (pg_dumpall), table exclusion, disk space checks, backup verification, webhook integrations, and Docker secrets. Available for linux/amd64 and linux/arm64 in both Debian and Alpine variants.

⁠Quick Start

Create a docker-compose.yml (or copy a ready-made one — see Examples⁠ below):

services:
  postgres:
    image: postgres:17
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
    volumes:
      - pgdata:/var/lib/postgresql/data

  backup:
    image: ganiyevuz/postgres-backup-telegram:17
    depends_on:
      - postgres
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_DB: mydb
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
      SCHEDULE: "@daily"
      TELEGRAM_BOT_TOKEN: "${TELEGRAM_BOT_TOKEN}"
      TELEGRAM_CHAT_ID: "${TELEGRAM_CHAT_ID}"
    volumes:
      - backups:/backups

volumes:
  pgdata:
  backups:

docker compose up -d

New to the project? Follow the Getting Started guide⁠ for a zero-to-restorable-backup walkthrough.

⁠Examples

Ready-to-run Compose files live in examples/⁠. Pick the one closest to your need, copy it to docker-compose.yml, copy .env.example⁠ to .env and fill in your values, then docker compose up -d.

cp examples/docker-compose.minimal.yml docker-compose.yml
cp examples/.env.example .env        # then edit .env with real values
docker compose up -d

• Large files (> 50 MB): the official Bot API caps uploads at 50 MB; the two large-files-* examples lift that to 2 GB (mtproto = built-in, no container; server = self-hosted Bot API daemon). See docs/LARGE_FILES.md⁠.
• Multiple chats: set TELEGRAM_CHAT_ID to a comma-separated list — the backup is uploaded once and fanned out to every chat.

⁠Features

• Scheduled backups via go-cron with a configurable SCHEDULE.
• Rotating retention — last / daily / weekly / monthly slots via space-saving hard links.
• Multiple databases and cluster-wide dumps (pg_dumpall).
• Multiple formats — gzip SQL, directory (-Fd), each optionally GPG AES-256 encrypted.
• Telegram delivery — Bot API for small files, built-in MTProto upload up to 2 GB, multi-chat fan-out.
• Restore tooling — interactive, by-file, cross-database, or --from-telegram disaster recovery.
• Safety — backup verification, pg_isready and disk-space checks, flock against overlapping runs.
• Integrations — webhooks (pre/post/error), custom run-parts hooks, Docker secrets (*_FILE).
• REST API (opt-in) — trigger/observe/restore/download/delete backups and change runtime settings over HTTP, behind a bearer token. See docs/REST_API.md⁠.

⁠Documentation

Full doc index: docs/⁠.

⁠Configuration

All settings are environment variables; credentials also accept *_FILE (Docker secrets) variants that take precedence over the plain value. The most common:

See the Configuration Reference⁠ for the complete list.

⁠CLI Commands

Available inside the container via docker exec -it <container> <command>:

See CLI Commands⁠ for usage and example output.

⁠How Backups Work

Each cycle writes a timestamped file to last/, then hard-links it into daily/, weekly/, and monthly/ (shared inode — no extra disk). Retention cleanup runs after each successful backup, pruning each slot independently.

Details and diagrams: Architecture⁠.

⁠Hooks

Place executable scripts in /hooks; they run via run-parts with pre-backup, post-backup, or error. The bundled 00-webhook implements the WEBHOOK_* variables — add your own alongside it.

⁠Security Notes

• Run the container as postgres:postgres for least-privilege operation.
• Use Docker secrets (*_FILE variables) instead of plain-text passwords in production.
• Enable BACKUP_ENCRYPTION_KEY to encrypt backups at rest with GPG AES-256.
• The healthcheck runs on an internal port (8080 by default) — do not expose it publicly unless needed.

⁠File permissions for the backup volume

# Debian-based image (UID 999)
mkdir -p /var/opt/pgbackups && chown -R 999:999 /var/opt/pgbackups

# Alpine-based image (UID 70)
mkdir -p /var/opt/pgbackups && chown -R 70:70 /var/opt/pgbackups

⁠Image Tags

Images are published as ganiyevuz/postgres-backup-telegram:<pg-version>[-alpine].

⁠License

See LICENSE⁠ for details.