Postgres S3 Backups

A simple utility to backup Postgres databases to S3-compatible services, built with Bun.

Features

• Automated Backups: Schedule backups using cron expressions.
• S3-Compatible: Works with AWS S3, Cloudflare R2, MinIO and other S3-compatible services.
• Compression: Compresses backups using Gzip for efficient storage.
• Flexible: Supports custom pg_dump options.
• Run on Startup: Option to run a backup immediately on startup.
• Single Shot Mode: Run once and exit, ideal for CI/CD pipelines.

Prerequisites

Before you begin, ensure you have met the following requirements:

• You have installed the latest version of Bun
• You have a working PostgreSQL database.
• You have an S3-compatible storage service and your credentials.
• Or, you have Docker installed to run the utility in a containerized environment.

Environment Variables

To configure the backup utility, you need to set the following environment variables. You can create a .env file in the root of the project based on the .env.example file.

Variable	Description	Default
AWS_ACCESS_KEY_ID	Your S3 access key ID.
AWS_SECRET_ACCESS_KEY	Your S3 secret access key.
S3_BUCKET	The name of your S3 bucket.
S3_REGION	The region of your S3 bucket.
S3_ENDPOINT	The endpoint for your S3-compatible service (optional).
DATABASE_URL	The connection URL for your PostgreSQL database.
BACKUP_CRON_SCHEDULE	The cron schedule for backups. See crontab.guru for help.	0 0 * * *
BACKUP_FILE_PREFIX	The prefix for the backup file name.	backup
BUCKET_SUBFOLDER	A subfolder within the bucket to store backups (optional).
BACKUP_OPTIONS	Extra options to pass to the pg_dump command (optional).
RUN_ON_STARTUP	Whether to run a backup on startup.	false
SINGLE_SHOT_MODE	Whether to run a single backup and then exit.	false
PG_VERSION	The version of PostgreSQL to use for pg_dump on Docker.	18

Usage

1. Install dependencies:

bun install

2. Set up your environment variables:

Create a .env file in the root of the project and add the required environment variables.

3. Run the backup utility:

bun start

Running with Docker

You can also run this utility using Docker. First, build the Docker image:

docker build -t postgres-s3-backups .

Then, you can run the backup utility using the following command. Remember to replace the placeholder values with your actual environment variables.

docker run --env-file .env postgres-s3-backups

References and inspirations

• https://github.com/railwayapp-templates/postgres-s3-backups

License

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