{"id":13437413,"url":"https://github.com/prodrigestivill/docker-postgres-backup-local","last_synced_at":"2025-05-14T23:07:47.539Z","repository":{"id":40257675,"uuid":"72207180","full_name":"prodrigestivill/docker-postgres-backup-local","owner":"prodrigestivill","description":"Backup PostgresSQL to local filesystem with periodic backups and rotate backups.","archived":false,"fork":false,"pushed_at":"2024-12-10T18:29:39.000Z","size":133,"stargazers_count":910,"open_issues_count":12,"forks_count":147,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-13T20:39:14.675Z","etag":null,"topics":["backup","docker","docker-image","postgres","postgresql"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/prodrigestivill/postgres-backup-local","language":"Shell","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/prodrigestivill.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}},"created_at":"2016-10-28T12:54:19.000Z","updated_at":"2025-04-12T16:26:27.000Z","dependencies_parsed_at":"2022-07-08T07:32:10.053Z","dependency_job_id":"59d9a3e3-f5eb-4a05-a431-1706e2909084","html_url":"https://github.com/prodrigestivill/docker-postgres-backup-local","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prodrigestivill%2Fdocker-postgres-backup-local","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prodrigestivill%2Fdocker-postgres-backup-local/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prodrigestivill%2Fdocker-postgres-backup-local/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prodrigestivill%2Fdocker-postgres-backup-local/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prodrigestivill","download_url":"https://codeload.github.com/prodrigestivill/docker-postgres-backup-local/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243362,"owners_count":22038046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","docker","docker-image","postgres","postgresql"],"created_at":"2024-07-31T03:00:56.771Z","updated_at":"2025-05-14T23:07:42.516Z","avatar_url":"https://github.com/prodrigestivill.png","language":"Shell","funding_links":[],"categories":["HarmonyOS","Shell"],"sub_categories":["Windows Manager"],"readme":"![Docker pulls](https://img.shields.io/docker/pulls/prodrigestivill/postgres-backup-local)\n![GitHub actions](https://github.com/prodrigestivill/docker-postgres-backup-local/actions/workflows/ci.yml/badge.svg?branch=main)\n\n# postgres-backup-local\n\nBackup PostgresSQL to the local filesystem with periodic rotating backups, based on [schickling/postgres-backup-s3](https://hub.docker.com/r/schickling/postgres-backup-s3/).\nBackup multiple databases from the same host by setting the database names in `POSTGRES_DB` separated by commas or spaces.\n\nSupports the following Docker architectures: `linux/amd64`, `linux/arm64`, `linux/arm/v7`, `linux/s390x`, `linux/ppc64le`.\n\nPlease consider reading detailed the [How the backups folder works?](#how-the-backups-folder-works).\n\nThis application requires the docker volume `/backups` to be a POSIX-compliant filesystem to store the backups (mainly with support for hardlinks and softlinks). So filesystems like VFAT, EXFAT, SMB/CIFS, ... can't be used with this docker image.\n\n## Usage\n\nDocker:\n\n```sh\ndocker run -u postgres:postgres -e POSTGRES_HOST=postgres -e POSTGRES_DB=dbname -e POSTGRES_USER=user -e POSTGRES_PASSWORD=password  prodrigestivill/postgres-backup-local\n```\n\nDocker Compose:\n\n```yaml\nversion: '2'\nservices:\n    postgres:\n        image: postgres\n        restart: always\n        environment:\n            - POSTGRES_DB=database\n            - POSTGRES_USER=username\n            - POSTGRES_PASSWORD=password\n         #  - POSTGRES_PASSWORD_FILE=/run/secrets/db_password \u003c-- alternative for POSTGRES_PASSWORD (to use with docker secrets)\n    pgbackups:\n        image: prodrigestivill/postgres-backup-local\n        restart: always\n        user: postgres:postgres # Optional: see below\n        volumes:\n            - /var/opt/pgbackups:/backups\n        links:\n            - postgres\n        depends_on:\n            - postgres\n        environment:\n            - POSTGRES_HOST=postgres\n            - POSTGRES_DB=database\n            - POSTGRES_USER=username\n            - POSTGRES_PASSWORD=password\n         #  - POSTGRES_PASSWORD_FILE=/run/secrets/db_password \u003c-- alternative for POSTGRES_PASSWORD (to use with docker secrets)\n            - POSTGRES_EXTRA_OPTS=-Z1 --schema=public --blobs\n            - SCHEDULE=@daily\n            - BACKUP_ON_START=TRUE\n            - BACKUP_KEEP_DAYS=7\n            - BACKUP_KEEP_WEEKS=4\n            - BACKUP_KEEP_MONTHS=6\n            - HEALTHCHECK_PORT=8080\n```\n\nFor security reasons it is recommended to run it as user `postgres:postgres`.\n\nIn case of running as `postgres` user, the system administrator must initialize the permission of the destination folder as follows:\n```sh\n# for default images (debian)\nmkdir -p /var/opt/pgbackups \u0026\u0026 chown -R 999:999 /var/opt/pgbackups\n# for alpine images\nmkdir -p /var/opt/pgbackups \u0026\u0026 chown -R 70:70 /var/opt/pgbackups\n```\n\n### Environment Variables\n\nMost variables are the same as in the [official postgres image](https://hub.docker.com/_/postgres/).\n\n| env variable | description |\n|--|--|\n| BACKUP_DIR | Directory to save the backup at. Defaults to `/backups`. |\n| BACKUP_SUFFIX | Filename suffix to save the backup. Defaults to `.sql.gz`. |\n| BACKUP_ON_START | If set to `TRUE` performs an backup on each container start or restart. Defaults to `FALSE`. |\n| BACKUP_KEEP_DAYS | Number of daily backups to keep before removal. Defaults to `7`. |\n| BACKUP_KEEP_WEEKS | Number of weekly backups to keep before removal. Defaults to `4`. |\n| BACKUP_KEEP_MONTHS | Number of monthly backups to keep before removal. Defaults to `6`. |\n| BACKUP_KEEP_MINS | Number of minutes for `last` folder backups to keep before removal. Defaults to `1440`. |\n| BACKUP_LATEST_TYPE | Type of `latest` pointer (`symlink`,`hardlink`,`none`). Defaults to `symlink`. |\n| VALIDATE_ON_START | If set to `FALSE` does not validate the configuration on start. Disabling this is not recommended. Defaults to `TRUE`. |\n| HEALTHCHECK_PORT | Port listening for cron-schedule health check. Defaults to `8080`. |\n| POSTGRES_DB | Comma or space separated list of postgres databases to backup. If POSTGRES_CLUSTER is set this refers to the database to connect to for dumping global objects and discovering what other databases should be dumped (typically is either `postgres` or `template1`). Required. |\n| POSTGRES_DB_FILE | Alternative to POSTGRES_DB, but with one database per line, for usage with docker secrets. |\n| POSTGRES_EXTRA_OPTS | Additional [options](https://www.postgresql.org/docs/12/app-pgdump.html#PG-DUMP-OPTIONS) for `pg_dump` (or `pg_dumpall` [options](https://www.postgresql.org/docs/12/app-pg-dumpall.html#id-1.9.4.13.6) if POSTGRES_CLUSTER is set). Defaults to `-Z1`. |\n| POSTGRES_CLUSTER | Set to `TRUE` in order to use `pg_dumpall` instead. Also set POSTGRES_EXTRA_OPTS to any value or empty since the default value is not compatible with `pg_dumpall`. |\n| POSTGRES_HOST | Postgres connection parameter; postgres host to connect to. Required. |\n| POSTGRES_PASSWORD | Postgres connection parameter; postgres password to connect with. Required. |\n| POSTGRES_PASSWORD_FILE | Alternative to POSTGRES_PASSWORD, for usage with docker secrets. |\n| POSTGRES_PASSFILE_STORE | Alternative to POSTGRES_PASSWORD in [passfile format](https://www.postgresql.org/docs/12/libpq-pgpass.html#LIBPQ-PGPASS), for usage with postgres clusters. |\n| POSTGRES_PORT | Postgres connection parameter; postgres port to connect to. Defaults to `5432`. |\n| POSTGRES_USER | Postgres connection parameter; postgres user to connect with. Required. |\n| POSTGRES_USER_FILE | Alternative to POSTGRES_USER, for usage with docker secrets. |\n| SCHEDULE | [Cron-schedule](http://godoc.org/github.com/robfig/cron#hdr-Predefined_schedules) specifying the interval between postgres backups. Defaults to `@daily`. |\n| TZ | [POSIX TZ variable](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html) specifying the timezone used to evaluate SCHEDULE cron (example \"Europe/Paris\"). |\n| WEBHOOK_URL | URL to be called after an error or after a successful backup (POST with a JSON payload, check `hooks/00-webhook` file for more info). Default disabled. |\n| WEBHOOK_ERROR_URL | URL to be called in case backup fails. Default disabled. |\n| WEBHOOK_PRE_BACKUP_URL | URL to be called when backup starts. Default disabled. |\n| WEBHOOK_POST_BACKUP_URL | URL to be called when backup completes successfully. Default disabled. |\n| WEBHOOK_EXTRA_ARGS | Extra arguments for the `curl` execution in the webhook (check `hooks/00-webhook` file for more info). |\n\n#### Special Environment Variables\n\nThis variables are not intended to be used for normal deployment operations:\n\n| env variable | description |\n|--|--|\n| POSTGRES_PORT_5432_TCP_ADDR | Sets the POSTGRES_HOST when the latter is not set. |\n| POSTGRES_PORT_5432_TCP_PORT | Sets POSTGRES_PORT when POSTGRES_HOST is not set. |\n\n### How the backups folder works?\n\nFirst a new backup is created in the `last` folder with the full time.\n\nOnce this backup finish succefully then, it is hard linked (instead of coping to avoid use more space) to the rest of the folders (daily, weekly and monthly). This step replaces the old backups for that category storing always only the latest for each category (so the monthly backup for a month is always storing the latest for that month and not the first).\n\nSo the backup folder are structured as follows:\n\n* `BACKUP_DIR/last/DB-YYYYMMDD-HHmmss.sql.gz`: all the backups are stored separatly in this folder.\n* `BACKUP_DIR/daily/DB-YYYYMMDD.sql.gz`: always store (hard link) the **latest** backup of that day.\n* `BACKUP_DIR/weekly/DB-YYYYww.sql.gz`: always store (hard link) the **latest** backup of that week (the last day of the week will be Sunday as it uses ISO week numbers).\n* `BACKUP_DIR/monthly/DB-YYYYMM.sql.gz`: always store (hard link) the **latest** backup of that month (normally the ~31st).\n\nAnd the following symlinks are also updated after each successfull backup for simlicity:\n\n```\nBACKUP_DIR/last/DB-latest.sql.gz -\u003e BACKUP_DIR/last/DB-YYYYMMDD-HHmmss.sql.gz\nBACKUP_DIR/daily/DB-latest.sql.gz -\u003e BACKUP_DIR/daily/DB-YYYYMMDD.sql.gz\nBACKUP_DIR/weekly/DB-latest.sql.gz -\u003e BACKUP_DIR/weekly/DB-YYYYww.sql.gz\nBACKUP_DIR/monthly/DB-latest.sql.gz -\u003e BACKUP_DIR/monthly/DB-YYYYMM.sql.gz\n```\n\nFor **cleaning** the script removes the files for each category only if the new backup has been successfull.\nTo do so it is using the following independent variables:\n\n* BACKUP_KEEP_MINS: will remove files from the `last` folder that are older than its value in minutes after a new successfull backup without affecting the rest of the backups (because they are hard links).\n* BACKUP_KEEP_DAYS: will remove files from the `daily` folder that are older than its value in days after a new successfull backup.\n* BACKUP_KEEP_WEEKS: will remove files from the `weekly` folder that are older than its value in weeks after a new successfull backup (remember that it starts counting from the end of each week not the beggining).\n* BACKUP_KEEP_MONTHS: will remove files from the `monthly` folder that are older than its value in months (of 31 days) after a new successfull backup (remember that it starts counting from the end of each month not the beggining).\n\n### Hooks\n\nThe folder `hooks` inside the container can contain hooks/scripts to be run in differrent cases getting the exact situation as a first argument (`error`, `pre-backup` or `post-backup`).\n\nJust create an script in that folder with execution permission so that [run-parts](https://manpages.debian.org/stable/debianutils/run-parts.8.en.html) can execute it on each state change.\n\nPlease, as an example take a look in the script already present there that implements the `WEBHOOK_URL` functionality.\n\n### Manual Backups\n\nBy default this container makes daily backups, but you can start a manual backup by running `/backup.sh`.\n\nThis script as example creates one backup as the running user and saves it the working folder.\n\n```sh\ndocker run --rm -v \"$PWD:/backups\" -u \"$(id -u):$(id -g)\" -e POSTGRES_HOST=postgres -e POSTGRES_DB=dbname -e POSTGRES_USER=user -e POSTGRES_PASSWORD=password  prodrigestivill/postgres-backup-local /backup.sh\n```\n\n### Automatic Periodic Backups\n\nYou can change the `SCHEDULE` environment variable in `-e SCHEDULE=\"@daily\"` to alter the default frequency. Default is `daily`.\n\nMore information about the scheduling can be found [here](http://godoc.org/github.com/robfig/cron#hdr-Predefined_schedules).\n\nFolders `daily`, `weekly` and `monthly` are created and populated using hard links to save disk space.\n\n## Restore examples\n\nSome examples to restore/apply the backups.\n\n### Restore using the same container\n\nTo restore using the same backup container, replace `$BACKUPFILE`, `$CONTAINER`, `$USERNAME` and `$DBNAME` from the following command:\n\n```sh\ndocker exec --tty --interactive $CONTAINER /bin/sh -c \"zcat $BACKUPFILE | psql --username=$USERNAME --dbname=$DBNAME -W\"\n```\n\n### Restore using a new container\n\nReplace `$BACKUPFILE`, `$VERSION`, `$HOSTNAME`, `$PORT`, `$USERNAME` and `$DBNAME` from the following command:\n\n```sh\ndocker run --rm --tty --interactive -v $BACKUPFILE:/tmp/backupfile.sql.gz postgres:$VERSION /bin/sh -c \"zcat /tmp/backupfile.sql.gz | psql --host=$HOSTNAME --port=$PORT --username=$USERNAME --dbname=$DBNAME -W\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprodrigestivill%2Fdocker-postgres-backup-local","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprodrigestivill%2Fdocker-postgres-backup-local","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprodrigestivill%2Fdocker-postgres-backup-local/lists"}