{"id":50699621,"url":"https://github.com/ralscha/postgres-s3-backup","last_synced_at":"2026-06-09T08:32:50.778Z","repository":{"id":341880451,"uuid":"1171869431","full_name":"ralscha/postgres-s3-backup","owner":"ralscha","description":"Automated PostgreSQL backup sidecar for Docker environments with S3 support.","archived":false,"fork":false,"pushed_at":"2026-05-01T07:56:00.000Z","size":31,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T09:33:49.307Z","etag":null,"topics":["backup","postgres","postgresql","sidecar-container"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ralscha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-03T17:41:30.000Z","updated_at":"2026-05-01T07:53:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ralscha/postgres-s3-backup","commit_stats":null,"previous_names":["ralscha/postgres-s3-backup"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ralscha/postgres-s3-backup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralscha%2Fpostgres-s3-backup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralscha%2Fpostgres-s3-backup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralscha%2Fpostgres-s3-backup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralscha%2Fpostgres-s3-backup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ralscha","download_url":"https://codeload.github.com/ralscha/postgres-s3-backup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ralscha%2Fpostgres-s3-backup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34098932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backup","postgres","postgresql","sidecar-container"],"created_at":"2026-06-09T08:32:48.601Z","updated_at":"2026-06-09T08:32:50.773Z","avatar_url":"https://github.com/ralscha.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# postgres-s3-backup\n\nDocker sidecar and CLI tool for backing up PostgreSQL databases directly to S3-compatible storage, with optional encryption and scheduling.\n\n## Features\n\n- Backup PostgreSQL to S3 or any S3-compatible storage (MinIO, Cloudflare R2, etc.)\n- Restore latest backup or a specific backup by timestamp\n- **Encryption options**:\n  - Symmetric passphrase encryption via `PASSPHRASE` (age scrypt)\n  - Asymmetric X25519 encryption via `AGE_PUBLIC_KEY` — backup host only needs the public key\n- Optional retention cleanup via `BACKUP_KEEP_DAYS`\n- Schedule support: `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`, or any Go duration like `24h`\n- Configurable S3 addressing mode for compatibility (`auto`, `path`, `virtual`)\n\n\n## Environment variables\n\n### Required\n\n| Variable            | Description                                                 |\n|---------------------|-------------------------------------------------------------|\n| `S3_BUCKET`         | S3 bucket name                                              |\n| `S3_REGION`         | AWS/S3-compatible region (e.g. `us-east-1`, `auto` for R2) |\n| `POSTGRES_DATABASE` | Database name to back up or restore                         |\n| `POSTGRES_HOST`     | Postgres host                                               |\n| `POSTGRES_USER`     | Postgres username                                           |\n\n### Postgres\n\n| Variable            | Default  | Description                                                                            |\n|---------------------|----------|----------------------------------------------------------------------------------------|\n| `POSTGRES_PASSWORD` | _(empty)_ | Postgres password. Omit when using `.pgpass`, `pg_service.conf`, or `trust`/`peer` auth |\n| `POSTGRES_PORT`     | `5432`   | Postgres port                                                                          |\n| `PGDUMP_EXTRA_OPTS` | _(empty)_ | Extra flags passed verbatim to `pg_dump`                                               |\n| `PGDUMP_COMPRESS_LEVEL` | `6`  | Dump compression level `0`–`9`; ignored when `PGDUMP_EXTRA_OPTS` already sets `--compress`/`-Z` |\n\n### S3\n\n| Variable               | Default      | Description                                                          |\n|------------------------|--------------|----------------------------------------------------------------------|\n| `S3_ACCESS_KEY_ID`     | _(empty)_    | Access key (omit to use instance role / environment credentials)     |\n| `S3_SECRET_ACCESS_KEY` | _(empty)_    | Secret key                                                           |\n| `S3_ENDPOINT`          | _(empty)_    | Override endpoint URL for S3-compatible stores (e.g. MinIO)          |\n| `S3_PREFIX`            | _(empty)_    | Object key prefix (e.g. `backup`). Empty = store at bucket root.     |\n| `S3_ADDRESSING_MODE`   | `path`       | `auto`, `path`, or `virtual`                                         |\n\n### Encryption\n\n`PASSPHRASE` and `AGE_PUBLIC_KEY` are **mutually exclusive**. Leave both empty to disable encryption.\n\n| Variable          | Description                                                                                                   |\n|-------------------|---------------------------------------------------------------------------------------------------------------|\n| `PASSPHRASE`      | Symmetric scrypt passphrase for encrypt/decrypt. **Must match** on backup and restore hosts.                  |\n| `AGE_PUBLIC_KEY`  | X25519 public key (e.g. `age1...`). Backup requires only this; for **restore**, put the private key identity in `PASSPHRASE`. |\n| `AGE_WORK_FACTOR` | scrypt work factor used with `PASSPHRASE` (default `18`; valid `1`–`30`). Higher = slower but stronger KDF.   |\n\n#### Generating an X25519 key pair\n\n```sh\n# Install age: https://github.com/FiloSottile/age\nage-keygen -o backup.key\n# Public key is printed to stdout and stored in backup.key\n```\n\nSet `AGE_PUBLIC_KEY` to the public key (`age1...`) for backup.  \nFor restore, set `PASSPHRASE` to the full contents of `backup.key` (the identity file).\n\n### Scheduling \u0026 mode\n\n| Variable           | Default   | Description                                                                               |\n|--------------------|-----------|-------------------------------------------------------------------------------------------|\n| `SCHEDULE`         | _(empty)_ | Run interval. Empty = run once and exit. Examples: `@daily`, `@weekly`, `12h`             |\n| `BACKUP_KEEP_DAYS` | `0`       | Delete backups older than N days. `0` disables pruning.                                   |\n| `MODE`             | `backup`  | `backup`, `restore`, or `list`                                                            |\n| `RESTORE_TIMESTAMP`| _(empty)_ | Specific backup timestamp to restore (`2026-01-14T12:00:00`). Empty = restore latest.     |\n| `LOG_LEVEL`        | `info`    | `debug`, `info`, `warn`, or `error`                                                       |\n\n## Docker image\n\nPre-built images are available from the GitHub Container Registry:\n\n```sh\ndocker pull ghcr.io/ralscha/postgres-s3-backup:latest\n```\n\n## Sidecar usage example\n\nCopy `template.env` to `.env` and fill in values.\n\n```yaml\nservices:\n  postgres:\n    image: postgres:18-alpine\n    restart: unless-stopped\n    environment:\n      POSTGRES_USER: user\n      POSTGRES_PASSWORD: password\n      POSTGRES_DB: mydb\n\n  backup:\n    image: ghcr.io/ralscha/postgres-s3-backup:latest\n    env_file: .env\n    environment:\n      POSTGRES_HOST: postgres\n      POSTGRES_DATABASE: mydb\n      POSTGRES_USER: user\n      POSTGRES_PASSWORD: password\n      SCHEDULE: \"@daily\"\n      BACKUP_KEEP_DAYS: \"30\"\n    restart: unless-stopped\n```\n\n## Run as CLI tool\n\n**Backup once:**\n\n```sh\ndocker run --rm --env-file .env ghcr.io/ralscha/postgres-s3-backup:latest\n```\n\n**Scheduled backup** (set `SCHEDULE=@daily` in `.env`):\n\n```sh\ndocker run --env-file .env ghcr.io/ralscha/postgres-s3-backup:latest\n```\n\n**Restore latest:**\n\n```sh\ndocker run --rm --env-file .env -e MODE=restore ghcr.io/ralscha/postgres-s3-backup:latest\n```\n\n**Restore specific timestamp:**\n\n```sh\ndocker run --rm --env-file .env -e MODE=restore -e RESTORE_TIMESTAMP=2026-01-14T12:00:00 ghcr.io/ralscha/postgres-s3-backup:latest\n```\n\n**List available backup timestamps:**\n\n```sh\ndocker run --rm --env-file .env -e MODE=list ghcr.io/ralscha/postgres-s3-backup:latest\n```\n\nOutputs one timestamp per line (oldest first), suitable for use with `RESTORE_TIMESTAMP`.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fralscha%2Fpostgres-s3-backup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fralscha%2Fpostgres-s3-backup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fralscha%2Fpostgres-s3-backup/lists"}