GitHubHelp

minibikini/postgres-backup-rclone

★ 1Forks 0ShellGitHub ↗Compare

README

PostgreSQL Backup & Restore via Rclone

Tests License: MIT

A lightweight, reliable, and containerized utility to automate PostgreSQL backups and restores to AWS S3, MinIO, Google Cloud Storage, Backblaze B2, or any other cloud storage provider supported by Rclone.

Features

  • Automated Backups: Runs backups on a customizable cron schedule.
  • Direct Streaming: Streams pg_dump directly to Rclone's S3 upload (rcat) without saving intermediate dump files to disk, saving space and improving performance.
  • Easy Restores: Restore your database from the latest backup automatically, or target a specific file.
  • Robust Cron Environment: Environment variables are safely propagated to cron jobs.
  • Precise PostgreSQL Compatibility: Uses the official postgres:alpine base image ensuring pg_dump and psql clients match your database version exactly.
  • Customizable Rclone Backend: Configure any Rclone-supported backend via Docker environment variables.

Configuration Variables

The following environment variables can be configured to customize the database connection and S3 backup destination:

Variable Description Default
POSTGRES_HOST PostgreSQL server hostname. localhost
POSTGRES_PORT PostgreSQL server port. 5432
POSTGRES_USER PostgreSQL username. postgres
POSTGRES_PASSWORD PostgreSQL password. postgres
POSTGRES_DATABASE PostgreSQL database name to back up. postgres
BUCKET_NAME S3 bucket name. backups
BACKUP_SCHEDULE Cron schedule for automated backups. 0 1 * * * (Daily at 1:00 AM)
RCLONE_CONFIG_REMOTE_TYPE Rclone backend type (e.g. s3, gcs, b2, etc.) s3
RCLONE_CONFIG_REMOTE_PROVIDER Rclone S3 provider (e.g. Minio, AWS, etc.) Minio
RCLONE_CONFIG_REMOTE_ENDPOINT Endpoint URL of the storage provider. http://minio:9000
RCLONE_CONFIG_REMOTE_ACCESS_KEY_ID Storage access key ID. minioadmin
RCLONE_CONFIG_REMOTE_SECRET_ACCESS_KEY Storage secret access key. minioadmin

Quick Start (Docker Compose)

Add the backup service to your docker-compose.yml:

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: secret_password
      POSTGRES_USER: pg_user
      POSTGRES_DB: main_db

  backup:
    image: ghcr.io/minibikini/postgres-backup-rclone:latest
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_USER: pg_user
      POSTGRES_PASSWORD: secret_password
      POSTGRES_DATABASE: main_db
      BUCKET_NAME: my-app-backups
      BACKUP_SCHEDULE: "0 */6 * * *" # Every 6 hours
      RCLONE_CONFIG_REMOTE_TYPE: s3
      RCLONE_CONFIG_REMOTE_PROVIDER: AWS
      RCLONE_CONFIG_REMOTE_ACCESS_KEY_ID: YOUR_AWS_KEY
      RCLONE_CONFIG_REMOTE_SECRET_ACCESS_KEY: YOUR_AWS_SECRET
    depends_on:
      postgres:
        condition: service_healthy

Manual Operations

You can trigger manual backups and restores using docker compose run:

1. Trigger Manual Backup

docker compose run --rm backup backup.sh

This generates a backup file with the format: ${POSTGRES_DATABASE}-YYYY-MM-DD-HH-MM-SS.sql.gz.

2. Restore Database from the Latest Backup

docker compose run --rm backup restore.sh

This automatically fetches the newest .sql.gz file from your bucket and streams it into the database.

3. Restore Database from a Specific Backup File

docker compose run --rm backup restore.sh main_db-2026-07-11-10-30-00.sql.gz

Development & Testing

This project uses BATS (Bash Automated Testing System) for integration tests.

Run Integration Tests Locally

Ensure you have Node.js installed, then run:

npm install
npm test

The integration tests will spin up PostgreSQL, MinIO, and the Backup container via Docker Compose, perform manual backups, verify files in MinIO, execute restores, and validate the automated cron backup functionality.

License

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

Contributors

minibikini

Issues