From 42d544a9c03aa4b682189f2274c5c1bea346d635 Mon Sep 17 00:00:00 2001 From: Hristo Venev Date: Tue, 17 Oct 2023 22:44:23 +0300 Subject: Remember and retry running operation --- README.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 3040ca0..84ae7a4 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,13 @@ ## Overview -`pgbak` is a utility for PostgreSQL backups based on WAL archiving. Data is stored in a local directory provided through the `PGBAK` environment variable. +`pgbak` is a robust WAL archiver for PostgreSQL. It automates compression as well as the creation of full snapshots. -Note that `pgbak` itself does not back up the data to any remote location. Instead the user must provide a script at `$PGBAK/scripts/backup` which is invoked when a backup needs to be performed. If no remote backups are desired, it can simply be a symlink to `/bin/true`. +Data is stored in a local directory provided through the `PGBAK` environment variable. A user-provided script may back it up to a remote location if desired. + +Some tasks are performed by a "sync" process that is automatically started in the background when necessary. This includes taking full snapshots and running the backup script. + +Note that `pgbak` is not a full point-in-time recovery archiver. In some cases, for example during snapshots, some WAL files may be missed. ## Backup directory structure @@ -22,30 +26,26 @@ Currently `pgbak` never deletes old backup directories. The following subcommands are provided: -- `pgbak wal PATH` — Archive the given WAL file and exit. A background sync process will be started if one isn't running. -- `pgbak sync` — Run sync in the foreground if necessary. +- `pgbak wal PATH` — Archive the given WAL file and exit. A background sync process will be started if necessary. +- `pgbak sync` — Run sync in the foreground if a previous run was interrupted. - `pgbak force-sync` — Run sync in the foreground. The `backup` script is always invoked. +- `pgbak full-sync` — Run sync in the foreground. Take a full snapshot and run the `backup` script. - `pgbak wait [TIMEOUT]` — If a sync is running, wait for it to finish. The `TIMEOUT` is in seconds and defaults to infinity. Exits with non-zero status on error or timeout. -The sync process is responsible for maintaining the `$PGBAK` directory. In particular, it - -- creates a new full backup every now and again -- calls `$PGBAK/scripts/backup` - ### Writing `$PGBAK/scripts/backup` When the `backup` script is started, the current directory is set to the subdirectory of `$PGBAK` that needs to be backed up. The script is given the following arguments: -- the timestamp of the base backup -- the current timestamp +1. the timestamp of the base backup +2. the current timestamp -Existing files will never disappear/change, provided the base backup timestamp is the same. However, new compressed WAL files may appear at any time. If this happens while the `backup` script is running, it will be called again with a refreshed current timestamp. +Existing files will never disappear or change, provided the base backup timestamp is the same. However, new compressed WAL files may appear at any time. If this happens while the `backup` script is running, it will be called again with a refreshed current timestamp. -On failure, the `backup` script will be retried indefinitely. The timestamps will be the same if no new WAL files have appeared. +On failure, the `backup` script will be retried indefinitely. The "current timestamp" will be the same if no new WAL files have appeared. ### Restoring from a backup -In order to restore from a backup, simply extract `base.tzst` to an empty `$PGDATA` directory and uncompress all WAL files into `$PGDATA/pg_wal`. +To restore from a backup, simply extract `base.tzst` to an empty `$PGDATA` directory and uncompress all WAL files into `$PGDATA/pg_wal`. Recovery can take quite a while if many WAL files need to be replayed. It may be beneficial to do it without `fsync` and instead `sync` later: @@ -88,6 +88,6 @@ To make your first backup, simply restart postgres and call `pg_switch_wal()`. ## Misc -`pgbak` uses [Zstandard](http://www.zstd.net/)'s command-line tool for compression. The compression options may be tweaked in `config.h`. +By default `pgbak` uses [Zstandard](http://www.zstd.net/)'s command-line tool for compression. The compression command and options may be tweaked in `config.h`. Currently only Linux is supported because of `O_TMPFILE` and `F_OFD_SETLK`. -- cgit