jkaninda/pg-bkup repository overview

⁠PG-BKUP

PG-BKUP is a Docker container image designed to backup, restore, and migrate PostgreSQL databases. It supports a variety of storage options and ensures data security through GPG encryption.

PG-BKUP is designed for seamless deployment on Docker and Kubernetes, simplifying PostgreSQL backup, restoration, and migration across environments. It is a lightweight, multi-architecture solution compatible with Docker, Docker Swarm, Kubernetes, and other container orchestration platforms.

⁠Features

• Flexible Storage Backends:

  • Local filesystem
  • Amazon S3 & S3-compatible storage (e.g., MinIO, Wasabi)
  • FTP
  • SSH-compatible storage
  • Azure Blob storage

• Data Security:

  • Backups can be encrypted using GPG to ensure confidentiality.

• Deployment Flexibility:

  • Available as the jkaninda/pg-bkup⁠ Docker image.
  • Deployable on Docker, Docker Swarm, and Kubernetes.
  • Supports recurring backups of PostgreSQL databases when deployed:
    • On Docker for automated backup schedules.
    • As a Job or CronJob on Kubernetes.

• Notifications:

  • Get real-time updates on backup success or failure via:
    • Telegram
    • Email

⁠💡Use Cases

• Scheduled Backups: Automate recurring backups using Docker or Kubernetes.
• Disaster Recovery: Quickly restore backups to a clean PostgreSQL instance.
• Database Migration: Seamlessly move data across environments using the built-in migrate feature.
• Secure Archiving: Keep backups encrypted and safely stored in the cloud or remote servers.

⁠🚀 Why Use PG-BKUP?

PG-BKUP isn't just another PostgreSQL backup tool, it's a robust, production-ready solution purpose-built for modern DevOps workflows.

Here’s why developers, sysadmins, and DevOps choose PG-BKUP:

⁠✅ All-in-One Backup, Restore & Migration

Whether you're backing up a single database, restoring critical data, or migrating across environments, PG-BKUP handles it all with a single, unified CLI no scripting gymnastics required.

⁠🔄 Works Everywhere You Deploy

Designed to be cloud-native:

• Runs seamlessly on Docker, Docker Swarm, and Kubernetes
• Supports CronJobs for automated scheduled backups
• Compatible with GitOps and CI/CD workflows

⁠☁️ Flexible Storage Integrations

Store your backups anywhere:

• Local disks
• Amazon S3, MinIO, Wasabi, Azure Blob, FTP, SSH

⁠🔒 Enterprise-Grade Security

• GPG Encryption: Protect sensitive data with optional encryption before storing backups locally or in the cloud.
• Secure Storage Options: Supports S3, Azure Blob, SFTP, and SSH with encrypted transfers, keeping backups safe from unauthorized access.

⁠📬 Instant Notifications

Stay in the loop with real-time notifications via Telegram and Email. Know immediately when a backup succeeds—or fails.

⁠🏃‍♂️ Lightweight and Fast

Written in Go, PG-BKUP is fast, multi-arch compatible (amd64, arm64, arm/v7), and optimized for minimal memory and CPU usage. Ideal for both cloud and edge deployments.

⁠🧪 Tested. Verified. Trusted.

Actively maintained with automated testing, Docker image size optimizations, and verified support across major container platforms.

⁠Supported PostgreSQL Versions

PG-BKUP supports PostgreSQL versions 9.5 and above, ensuring compatibility with most modern PostgreSQL deployments.

⁠✅ Verified Platforms

PG-BKUP has been tested and runs successfully on:

• Docker
• Docker Swarm
• Kubernetes
• OpenShift

⁠Documentation is found at https://jkaninda.github.io/pg-bkup⁠

⁠Useful links

• Docker Hub⁠
• Github⁠

⁠MySQL solution :

• MySQL⁠

⁠Quickstart

⁠Simple Backup Using Docker CLI

To perform a one-time backup, bind your local volume to /backup in the container and run the backup command:

docker run --rm --network your_network_name \
  -v $PWD/backup:/backup/ \
  -e "DB_HOST=dbhost" \
  -e "DB_PORT=5432" \
  -e "DB_USERNAME=username" \
  -e "DB_PASSWORD=password" \
  jkaninda/pg-bkup backup -d database_name

Alternatively, use an environment file (--env-file) for configuration:

docker run --rm --network your_network_name \
  --env-file your-env-file \
  -v $PWD/backup:/backup/ \
  jkaninda/pg-bkup backup -d database_name

⁠Backup Schema Only

To back up only the schema of a specific database, use the --schema-only flag:

docker run --rm --network your_network_name \
  -v $PWD/backup:/backup/ \
  -e "DB_HOST=dbhost" \
  -e "DB_PORT=5432" \
  -e "DB_USERNAME=username" \
  -e "DB_PASSWORD=password" \
  jkaninda/pg-bkup backup -d database_name --schema-only

⁠Backup specific tables

To back up specific tables within a database, use the --tables or -t flag followed by a comma-separated list of table names:

docker run --rm --network your_network_name \
  -v $PWD/backup:/backup/ \
  -e "DB_HOST=dbhost" \
  -e "DB_PORT=5432" \
  -e "DB_USERNAME=username" \
  -e "DB_PASSWORD=password" \
  jkaninda/pg-bkup backup -d database_name --tables table1,table2

⁠Backup All Databases

To back up all databases on the server, use the --all-databases or -a flag. By default, this creates individual backup files for each database.

docker run --rm --network your_network_name \
  -v $PWD/backup:/backup/ \
  -e "DB_HOST=dbhost" \
  -e "DB_PORT=5432" \
  -e "DB_USERNAME=username" \
  -e "DB_PASSWORD=password" \
  jkaninda/pg-bkup backup --all-databases --disable-compression

⁠Migrate database

The migrate command allows you to transfer a PostgreSQL database from a source to a target database in a single step, combining backup and restore operations.

docker run --rm --network your_network_name \
  --env-file your-env \
  jkaninda/pg-bkup migrate

For database migration, refer to the documentation⁠.

⁠Simple Restore Using Docker CLI

To restore a database, bind your local volume to /backup and run the restore command:

docker run --rm --network your_network_name \
  -v $PWD/backup:/backup/ \
  -e "DB_HOST=dbhost" \
  -e "DB_PORT=5432" \
  -e "DB_USERNAME=username" \
  -e "DB_PASSWORD=password" \
  jkaninda/pg-bkup restore -d database_name -f backup_file.sql.gz

⁠Backup with Docker Compose

Below is an example of a docker-compose.yml file for running a one-time backup:

services:
  pg-bkup:
    # In production, pin your image tag to a specific release version instead of `latest`.
    # See available releases: https://github.com/jkaninda/pg-bkup/releases
    image: jkaninda/pg-bkup
    container_name: pg-bkup
    command: backup
    volumes:
      - ./backup:/backup
    environment:
      - DB_PORT=5432
      - DB_HOST=postgres
      - DB_NAME=foo
      - DB_USERNAME=bar
      - DB_PASSWORD=password
      - TZ=Europe/Paris
    networks:
      - web

networks:
  web:

⁠Recurring Backups with Docker

You can schedule recurring backups using the --cron-expression or -e flag:

docker run --rm --network network_name \
  -v $PWD/backup:/backup/ \
  -e "DB_HOST=hostname" \
  -e "DB_USERNAME=user" \
  -e "DB_PASSWORD=password" \
  jkaninda/pg-bkup backup -d dbName --cron-expression "@every 15m"

For predefined schedules, refer to the documentation⁠.

⁠Running Multiple Backups in a Single Container

PG-BKUP supports backing up multiple PostgreSQL databases in a single run using a configuration file. You can pass the file using the --config or -c flag, or by setting the BACKUP_CONFIG_FILE environment variable.

This is ideal for setups where multiple services or applications each require independent database backups.

⁠Example Configuration File

Below is a sample config.yaml file that defines multiple databases along with their respective connection and backup settings:

# Optional: Global cron expression for scheduled backups.
# Examples: "@daily", "@every 5m", "0 3 * * *"
cronExpression: ""

databases:
  - host: lldap-db             # Optional: Overrides DB_HOST or uses DB_HOST_LLDAP.
    port: 5432                 # Optional: Defaults to 5432. Overrides DB_PORT or uses DB_PORT_LLDAP.
    name: lldap                # Required: Database name
    user: lldap                # Optional: Can override via DB_USERNAME or uses DB_USERNAME_LLDAP.
    password: password         # Optional: Can override via DB_PASSWORD or uses DB_PASSWORD_LLDAP.
    path: /s3-path/lldap       # Required: Destination path (S3, FTP, SSH, etc.)

  - host: keycloak-db
    port: 5432
    name: keycloak
    user: keycloak
    password: password
    path: /s3-path/keycloak

  - host: gitea-db
    port: 5432
    name: gitea
    user: gitea
    password: ""               # Can be empty or sourced from DB_PASSWORD_GITEA
    path: /s3-path/gitea

⁠Docker Compose Setup

To run backups using this configuration in Docker Compose:

1. Mount the configuration file into the container.
2. Set the BACKUP_CONFIG_FILE environment variable or use the -c flag in the command.

⁠Sample docker-compose.yaml

services:
  pg-bkup:
    image: jkaninda/pg-bkup
    container_name: pg-bkup
    command: backup -c /backup/config.yaml
    volumes:
      - ./backup:/backup                # Backup target directory
      - ./config.yaml:/backup/config.yaml  # Mount configuration file
    environment:
      - DB_PASSWORD_GITEA=password
      - BACKUP_CRON_EXPRESSION=@daily   # Optional: Overrides config file cronExpression
    networks:
      - web

networks:
  web:

⁠Deploy on Kubernetes

For Kubernetes, you can deploy pg-bkup as a Job or CronJob. Below are examples for both.

⁠Kubernetes Backup Job

This example defines a one-time backup job:

apiVersion: batch/v1
kind: Job
metadata:
  name: backup-job
spec:
  ttlSecondsAfterFinished: 100
  template:
    spec:
      containers:
        - name: pg-bkup
          # Pin the image tag to a specific release version in production.
          # See available releases: https://github.com/jkaninda/pg-bkup/releases
          image: jkaninda/pg-bkup
          command: ["backup", "-d", "db_name"]
          resources:
            limits:
              memory: "128Mi"
              cpu: "500m"
          env:
            - name: DB_HOST
              value: "postgres"
            - name: DB_USERNAME
              value: "postgres"
            - name: DB_PASSWORD
              value: "password"
          volumeMounts:
            - mountPath: /backup
              name: backup
      volumes:
        - name: backup
          hostPath:
            path: /home/toto/backup # Directory location on the host
            type: Directory # Optional field
      restartPolicy: Never

⁠Kubernetes CronJob for Scheduled Backups

For scheduled backups, use a CronJob:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: pg-bkup-cronjob
spec:
  schedule: "0 2 * * *" # Runs daily at 2 AM
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: pg-bkup
              image: jkaninda/pg-bkup
              command: ["backup", "-d", "db_name"]
              env:
                - name: DB_HOST
                  value: "postgres"
                - name: DB_USERNAME
                  value: "postgres"
                - name: DB_PASSWORD
                  value: "password"
              volumeMounts:
                - mountPath: /backup
                  name: backup
          volumes:
            - name: backup
              hostPath:
                path: /home/toto/backup
                type: Directory
          restartPolicy: OnFailure

⁠Give a Star! ⭐

If this project helped you, do not skip on giving it a star on GitHub⁠.Thanks!

⁠Available image registries

This Docker image is published to both Docker Hub and the GitHub container registry. Depending on your preferences and needs, you can reference both jkaninda/pg-bkup as well as ghcr.io/jkaninda/pg-bkup:

docker pull jkaninda/pg-bkup
docker pull ghcr.io/jkaninda/pg-bkup

Documentation references Docker Hub, but all examples will work using ghcr.io just as well.

⁠References

We created this image as a simpler and more lightweight alternative to existing solutions. Here’s why:

• Lightweight: Written in Go, the image is optimized for performance and minimal resource usage.
• Multi-Architecture Support: Supports arm64 and arm/v7 architectures.
• Docker Swarm Support: Fully compatible with Docker in Swarm mode.
• Kubernetes Support: Designed to work seamlessly with Kubernetes.

⁠License

This project is licensed under the MIT License. See the LICENSE file for details.

⁠Authors

Jonas Kaninda

• https://github.com/jkaninda⁠

⁠Copyright

Copyright (c) [2024] [Jonas Kaninda]