Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
ledermann committed Feb 6, 2025
1 parent 2c44f06 commit 2b93825
Showing 1 changed file with 21 additions and 25 deletions.
46 changes: 21 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,25 @@
# Introduction

This project provides Docker images to periodically back up a PostgreSQL database to AWS S3, and to restore from the backup as needed.

# Usage

## Backup

```yaml
services:
postgres:
image: postgres:16
image: postgres:17-alpine
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: password

backup:
image: eeshugerman/postgres-backup-s3:16
image: ghcr.io/solectrus/postgres-s3-backup:17
environment:
SCHEDULE: '@weekly' # optional
BACKUP_KEEP_DAYS: 7 # optional
PASSPHRASE: passphrase # optional
SCHEDULE: '@weekly' # optional
BACKUP_KEEP_DAYS: 7 # optional
PASSPHRASE: passphrase # optional
S3_REGION: region
S3_ACCESS_KEY_ID: key
S3_SECRET_ACCESS_KEY: secret
Expand All @@ -28,18 +31,20 @@ services:
POSTGRES_PASSWORD: password
```
- Images are tagged by the major PostgreSQL version supported: `12`, `13`, `14`, `15` or `16`.
- Images are tagged by the major PostgreSQL version supported: `13`, `14`, `15`, `16` or `17`.
- The `SCHEDULE` variable determines backup frequency. See go-cron schedules documentation [here](http://godoc.org/github.com/robfig/cron#hdr-Predefined_schedules). Omit to run the backup immediately and then exit.
- If `PASSPHRASE` is provided, the backup will be encrypted using GPG.
- Run `docker exec <container name> sh backup.sh` to trigger a backup ad-hoc.
- If `BACKUP_KEEP_DAYS` is set, backups older than this many days will be deleted from S3.
- Set `S3_ENDPOINT` if you're using a non-AWS S3-compatible storage provider.

## Restore

> [!CAUTION]
> DATA LOSS! All database objects will be dropped and re-created.

### ... from latest backup

```sh
docker exec <container name> sh restore.sh
```
Expand All @@ -48,40 +53,31 @@ docker exec <container name> sh restore.sh
> If your bucket has more than a 1000 files, the latest may not be restored -- only one S3 `ls` command is used

### ... from specific backup

```sh
docker exec <container name> sh restore.sh <timestamp>
```

# Development

## Build the image locally

`POSTGRES_VERSION` determines Postgres version.

```sh
DOCKER_BUILDKIT=1 docker build --build-arg POSTGRES_VERSION=17 .
```

## Run a simple test environment with Docker Compose

```sh
cp template.env .env
# fill out your secrets/params in .env
docker compose up -d
```

# Acknowledgements
This project is a fork and re-structuring of @schickling's [postgres-backup-s3](https://github.com/schickling/dockerfiles/tree/master/postgres-backup-s3) and [postgres-restore-s3](https://github.com/schickling/dockerfiles/tree/master/postgres-restore-s3).

## Fork goals
These changes would have been difficult or impossible merge into @schickling's repo or similarly-structured forks.
- dedicated repository
- automated builds
- support multiple PostgreSQL versions
- backup and restore with one image

## Other changes and features
- some environment variables renamed or removed
- uses `pg_dump`'s `custom` format (see [docs](https://www.postgresql.org/docs/10/app-pgdump.html))
- drop and re-create all database objects on restore
- backup blobs and all schemas by default
- no Python 2 dependencies
- filter backups on S3 by database name
- support encrypted (password-protected) backups
- support for restoring from a specific backup by timestamp
- support for auto-removal of old backups

This project is a fork of @eeshugerman's [postgres-backup-s3](https://github.com/eeshugerman/postgres-backup-s3) repository. Since the original project is no longer maintained, I decided to fork it and merge an important pull request ([#61](https://github.com/eeshugerman/postgres-backup-s3/pull/61)) to add support for PostgreSQL 17.

The original repository itself is a fork and restructuring of @schickling's [postgres-backup-s3](https://github.com/schickling/dockerfiles/tree/master/postgres-backup-s3) and [postgres-restore-s3](https://github.com/schickling/dockerfiles/tree/master/postgres-restore-s3).

0 comments on commit 2b93825

Please sign in to comment.