{"id":51489449,"url":"https://github.com/shaxzodbek-uzb/pgproof","last_synced_at":"2026-07-07T10:03:01.310Z","repository":{"id":366147640,"uuid":"1275229670","full_name":"shaxzodbek-uzb/pgproof","owner":"shaxzodbek-uzb","description":"Postgres \u0026 MySQL backups you've proven restore — encrypted, to S3/R2/local/Telegram, with a one-command restore-test and Telegram alerts.","archived":false,"fork":false,"pushed_at":"2026-06-20T12:34:51.000Z","size":68,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T14:27:11.769Z","etag":null,"topics":["age-encryption","backup","cli","cloudflare-r2","devops","disaster-recovery","golang","homelab","mysql","postgres","postgresql","restore","s3","self-hosted"],"latest_commit_sha":null,"homepage":null,"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/shaxzodbek-uzb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-06-20T12:22:29.000Z","updated_at":"2026-06-20T12:34:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shaxzodbek-uzb/pgproof","commit_stats":null,"previous_names":["shaxzodbek-uzb/pgproof"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/shaxzodbek-uzb/pgproof","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaxzodbek-uzb%2Fpgproof","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaxzodbek-uzb%2Fpgproof/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaxzodbek-uzb%2Fpgproof/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaxzodbek-uzb%2Fpgproof/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shaxzodbek-uzb","download_url":"https://codeload.github.com/shaxzodbek-uzb/pgproof/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaxzodbek-uzb%2Fpgproof/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35223385,"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-07-07T02:00:07.222Z","response_time":90,"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":["age-encryption","backup","cli","cloudflare-r2","devops","disaster-recovery","golang","homelab","mysql","postgres","postgresql","restore","s3","self-hosted"],"created_at":"2026-07-07T10:03:00.580Z","updated_at":"2026-07-07T10:03:01.303Z","avatar_url":"https://github.com/shaxzodbek-uzb.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# pgproof\n\n**Postgres \u0026 MySQL backups you've _proven_ restore.**\n\n[![CI](https://github.com/shaxzodbek-uzb/pgproof/actions/workflows/ci.yml/badge.svg)](https://github.com/shaxzodbek-uzb/pgproof/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/shaxzodbek-uzb/pgproof?sort=semver)](https://github.com/shaxzodbek-uzb/pgproof/releases)\n[![Go Report Card](https://goreportcard.com/badge/github.com/shaxzodbek-uzb/pgproof)](https://goreportcard.com/report/github.com/shaxzodbek-uzb/pgproof)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n\u003c/div\u003e\n\nA backup you haven't restored is a hope, not a backup. **pgproof** dumps your\ndatabase, encrypts it, ships it to S3/R2/local/Telegram — and then **restores it\ninto a throwaway database to prove it actually works.** If a backup can't be\nrestored, it pings you on Telegram *today*, not the morning your primary dies.\n\n```console\n$ pgproof backup\n• app: 24.1 MiB, verified ✓ (42 tables) → [r2, disk] in 4.3s\n```\n\nThat `verified ✓` is the whole point. Every other line of this README is in\nservice of it.\n\n---\n\n## Why another backup tool?\n\n| | restore-test built in | single static binary | encrypted | S3/R2 + Telegram | one-command restore |\n|---|:---:|:---:|:---:|:---:|:---:|\n| **pgproof** | ✅ **every backup** | ✅ | ✅ age | ✅ | ✅ |\n| `pg_dump` + cron + s3 | ❌ | — | DIY | DIY | ❌ |\n| postgres-backup-s3 (Docker) | ❌ | ❌ | gpg | ❌ Telegram | ❌ |\n| pgBackRest / Barman | manual | ❌ | ✅ | ❌ | partial |\n\npgBackRest and Barman are excellent for large, WAL-based, point-in-time setups.\npgproof is for the other 90%: a homelab, a side project, a small SaaS that just\nwants **nightly logical backups it can trust**, with zero moving parts.\n\n## Features\n\n- 🔁 **Verified restores** — after each backup, pgproof spins up a throwaway\n  database, restores into it, checks it has tables (and optionally that key\n  tables aren't empty), then drops it. No manual fire drills.\n- 🔒 **Encrypted at rest** — streaming [age](https://age-encryption.org)\n  encryption, passphrase or public-key. Multi-GB dumps never touch RAM.\n- ☁️ **Anywhere storage** — S3, **Cloudflare R2**, DigitalOcean Spaces, MinIO,\n  local/NAS path, and Telegram as a write-only off-site copy. Fan out to several\n  at once.\n- 📣 **It pages you** — Telegram alerts on success/failure and a\n  [healthchecks.io](https://healthchecks.io) dead-man's switch.\n- 🗂️ **Retention** — grandfather-father-son (`keep last / daily / weekly / monthly`).\n- ⏰ **Built-in scheduler** — run as a systemd/Docker service, no system cron required.\n- 📦 **One static binary** — no runtime, no agent, no database of its own.\n\n## Install\n\n**Install script (Linux/macOS):**\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/shaxzodbek-uzb/pgproof/main/install.sh | sh\n```\n\n**Go:**\n\n```sh\ngo install github.com/shaxzodbek-uzb/pgproof@latest\n```\n\n**Docker** (bundles the `postgresql-client` so dumps/restores work out of the box):\n\n```sh\ndocker run --rm -v \"$PWD/pgproof.yml:/etc/pgproof/pgproof.yml:ro\" \\\n  ghcr.io/shaxzodbek-uzb/pgproof:latest backup\n```\n\nOr grab a prebuilt binary from [Releases](https://github.com/shaxzodbek-uzb/pgproof/releases).\n\n\u003e pgproof shells out to your installed `pg_dump`/`pg_restore`/`psql`\n\u003e (or `mysqldump`/`mysql`). It auto-detects the newest client on the box, so a\n\u003e Postgres 17 server is dumped by a 17 client even if an older one is on `PATH`.\n\n## Quickstart\n\n```sh\npgproof init                 # writes a commented pgproof.yml\n$EDITOR pgproof.yml          # point it at your DB + a destination\npgproof test                 # check destination credentials\npgproof backup               # dump → encrypt → upload → VERIFY\npgproof list                 # see backups and their verify status\npgproof verify --db app      # re-prove the latest backup, on demand\npgproof restore --db app     # bring one back\n```\n\n## Configuration\n\n`pgproof init` writes a fully commented config; the canonical reference is\n[`pgproof.example.yml`](pgproof.example.yml). The essentials:\n\n```yaml\ndatabases:\n  - name: app\n    driver: postgres          # or mysql\n    host: 127.0.0.1\n    user: postgres\n    password: ${PGPASSWORD}   # ${ENV} interpolation everywhere\n    dbname: app\n\nencryption:\n  enabled: true\n  passphrase: ${PGPROOF_PASSPHRASE}\n\ndestinations:\n  - type: s3                  # AWS S3 / Cloudflare R2 / Spaces / MinIO\n    name: r2\n    bucket: my-backups\n    endpoint: https://\u003cacct\u003e.r2.cloudflarestorage.com\n    access_key: ${S3_ACCESS_KEY}\n    secret_key: ${S3_SECRET_KEY}\n\nverify:\n  enabled: true               # ← the reason this tool exists\n\nretention:\n  keep_last: 7\n  keep_daily: 7\n  keep_weekly: 4\n\nnotify:\n  telegram:\n    enabled: true\n    bot_token: ${TG_BOT_TOKEN}\n    chat_id: ${TG_CHAT_ID}\n```\n\nSecrets are read from the environment with `${VAR}` (and `${VAR:-default}`); a\n`${VAR}` written inside a comment is ignored, so documentation never trips the\nloader. Keep `pgproof.yml` mode `0600`.\n\n## How the restore-test works\n\nThis is the headline feature, so here's exactly what happens when `verify` is on:\n\n1. Connect to your server's maintenance database (`postgres`, or `admin_db`).\n2. `CREATE DATABASE pgproof_verify_\u003crandom\u003e`.\n3. Restore the just-made dump into it (`pg_restore` for custom format, `psql`\n   for plain, `mysql` for MySQL).\n4. Assert it's sane — at least `min_tables` tables came back, and any\n   `row_count_tables` you listed are non-empty.\n5. **Always** `DROP DATABASE` the throwaway, even if a step failed.\n\nSet `verify.from_remote: true` to download and decrypt the *stored* artifact and\nverify **that** — proving the encrypted copy in S3 round-trips end to end, not\njust the local dump.\n\nA backup that fails verification is still stored (storage is cheap, data is\nprecious) but the run exits non-zero and you get a failure alert.\n\n## Encryption\n\n```sh\npgproof keygen        # prints an age keypair for public-key mode\n```\n\n- **Passphrase mode** — simplest; set `encryption.passphrase`.\n- **Recipient mode** — put the *public* key on the backup host\n  (`encryption.recipients`); the *secret* key only needs to exist where you\n  restore (`encryption.identity`). The box making backups can't read its own\n  backups — nice if it's internet-facing.\n\n## Scheduling\n\nRun pgproof as a long-lived service (no system cron):\n\n```sh\npgproof run     # backs up on schedule.cron, optionally prunes after\n```\n\n\u003cdetails\u003e\u003csummary\u003esystemd unit\u003c/summary\u003e\n\n```ini\n[Unit]\nDescription=pgproof scheduled backups\nAfter=network-online.target\n\n[Service]\nExecStart=/usr/local/bin/pgproof -c /etc/pgproof/pgproof.yml run\nRestart=on-failure\nUser=pgproof\n\n[Install]\nWantedBy=multi-user.target\n```\n\u003c/details\u003e\n\nPrefer system cron? Just call `pgproof backup` — it's a clean one-shot.\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `init` | Write a sample config |\n| `backup` | Dump → encrypt → upload → verify (now) |\n| `verify [id]` | Re-prove a stored backup restores |\n| `restore` | Restore a backup into a live database |\n| `list` | List backups with size + verify status |\n| `prune` | Apply the retention policy |\n| `run` | Long-lived scheduler |\n| `test` | Check destination connectivity |\n| `keygen` | Generate an age keypair |\n\n## Security\n\n- Credentials are passed to client tools via `PGPASSFILE` / a `0600`\n  `--defaults-extra-file`, **never on argv** (so they can't leak via `ps`).\n- Backups are streamed through age; plaintext dumps live only in a `0700`\n  staging dir and are removed after each run.\n- Found a vulnerability? See [SECURITY.md](SECURITY.md).\n\n## Status \u0026 roadmap\n\nv0.1 is logical (`pg_dump`/`mysqldump`) backups. Postgres is first-class; MySQL\nis supported. On the roadmap: directory-format parallel dumps, restic-style\nincremental object storage, and per-database schedules. Issues and PRs welcome —\nsee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE) © Shaxzodbek Qambaraliyev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshaxzodbek-uzb%2Fpgproof","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshaxzodbek-uzb%2Fpgproof","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshaxzodbek-uzb%2Fpgproof/lists"}