Version v3.7.0 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot.
For up-to-date documentation, see the latest version.
Backup script, schedule, repository, and infrastructure
Backups can be invoked by built-in scripts, scheduled with node crontab,
managed by pgbackrest, and stored in backup repo,
which could be local disk filesystem or MinIO / S3, with different retention policies.
Script
You can create a backup with pgbackrest command with pg_dbsu user (postgres by default):
pgbackrest --stanza=pg-meta --type=full backup # create a full backup for cluster pg-meta
The stanza here is the database cluster name: pg_cluster, which is pg-meta for the default setup.
Pigsty has an alias pb and wrapper script pg-backup that fills the current cluster name as stanza:
alias
function pb(){localstanza=$(grep -o '\[[^][]*]' /etc/pgbackrest/pgbackrest.conf | head -n1 | sed 's/.*\[\([^]]*\)].*/\1/') pgbackrest --stanza=$stanza$@}pb ... # pgbackrest --stanza=pg-meta ...pb info # pgbackrest --stanza=pg-meta infopb backup # pgbackrest --stanza=pg-meta backup
script
pg-backup full # take an full backup = pgbackrest --stanza=pg-meta --type=incr backuppg-backup incr # take an incremental backup = pgbackrest --stanza=pg-meta --type=incr backuppg-backup diff # take an differential backup = pgbackrest --stanza=pg-meta --type=incr backup
Crontab
Pigsty is leveraging Linux’s crontab to schedule backups. You can define your backup policies with it
For example, most one-node config template will have the following node_crontab for backup.
You can design more sophisticated backup policies with crontab and pg-backup script, such as:
Full backup on Monday, incremental backup during weekdays
node_crontab:# make a full backup on monday 1am, and an incremental backup during weekdays- '00 01 * * 1 postgres /pg/bin/pg-backup full'- '00 01 * * 2,3,4,5,6,7 postgres /pg/bin/pg-backup'
To apply crontab change, use the node.yml to update the crontab on all nodes.
apply crontab
./node.yml -t node_crontab -l pg-meta # apply crontab change to the pg-meta group
pgbackrest
Here’s pigsty’s setup details for pgbackrest:
The pgbackrest backup tool is enabled and configured by default (pgbackrest_enabled)
Installed in the pg_install task in the pgsql.yml playbook, defined in pg_packages
tmp: /pg/spool is used as the temp spool directory for pgbackrest
data: /pg/backup is used, if the default local filesystem backup repo is selected.
Moreover, during the PITR Recovery process,
Pigsty will create a temp /pg/conf/pitr.conf pgbackrest config file.
And write postgres recovery log to the /pg/tmp/recovery.log file.
When a postgres cluster is created, pigsty will create an initial backup automatically.
It’s a tiny backup since the new cluster is almost empty.
It will leave a marker file /etc/pgbackrest/initial.done to avoid creating the initial backup again.
Set the pgbackrest_init_backup to false if you don’t want it.
Administration
Enable Backup
If you database cluster is created with pgbackrest_enable set to true, the backup will be enabled automatically.
If it created with the false value, you can enable the pgbackrest component with:
./pgsql.yml -t pg_backup # run the pgbackrest subtask
Remove Backup
Pigsty will remove pgbackrest backup stanza when removing the primary instance (pg_role = primary).
Use the pg_backup subtask to remove the backup only, and use the pg_rm_backup arg to keep backups.
If your backup repo is locked, (e.g., S3 / MinIO has a lock option), this operation will fail.
Backup Removal
Removing backup may lead to permanent data loss, it’s a dangerous operation, do with extreme caution.
List Backup
This command will list all backups in the pgbackrest repository (shared by all clusters)
pgbackrest info
Manual Backup
Pigsty has a built-in script /pg/bin/pg-backup which wraps the pgbackrest backup command.
pg-backup # take an incremental backuppg-backup full # take an full backuppg-backup incr # take an incremental backuppg-backup diff # take an differential backup
Base Backup
Pigsty has an alternative backup script /pg/bin/pg-basebackup which does not rely on pgbackrest, and gives you a physical copy of the database cluster.
The default backup dir is /pg/backup.
NAME
pg-basebackup -- make base backup from PostgreSQL instance
SYNOPSIS
pg-basebackup -sdfeukr
pg-basebackup --src postgres:/// --dst . --file backup.tar.lz4
DESCRIPTION
-s, --src, --url Backup source URL, optional, "postgres:///" by default, if password is required, it should be given in url, ENV or .pgpass
-d, --dst, --dir Where to put backup files, "/pg/backup" by default
-f, --file Overwrite default backup filename, "backup_${tag}_${date}.tar.lz4"-r, --remove .lz4 Files mtime before n minutes ago will be removed, default is 1200(20hour)-t, --tag Backup file tag, if not set, target cluster_name or local ip address will be used. Also used as part of DEFAULT filename
-k, --key Encryption key when --encrypt is specified, default key is ${tag}-u, --upload Upload backup files to cloud storage, (need your own implementation)-e, --encryption Encrypt with RC4 using OpenSSL, if not key is specified, tag is used as key
-h, --help Print this message
postgres@pg-meta-1:~$ pg-basebackup
[2025-07-13 06:16:05][INFO]================================================================[2025-07-13 06:16:05][INFO][INIT] pg-basebackup begin, checking parameters
[2025-07-13 06:16:05][DEBUG][INIT]#====== BINARY[2025-07-13 06:16:05][DEBUG][INIT] pg_basebackup : /usr/pgsql/bin/pg_basebackup
[2025-07-13 06:16:05][DEBUG][INIT] openssl : /usr/bin/openssl
[2025-07-13 06:16:05][DEBUG][INIT]#====== PARAMETER[2025-07-13 06:16:05][DEBUG][INIT] filename (-f) : backup_pg-meta_20250713.tar.lz4
[2025-07-13 06:16:05][DEBUG][INIT] src (-s) : postgres:///
[2025-07-13 06:16:05][DEBUG][INIT] dst (-d) : /pg/backup
[2025-07-13 06:16:05][DEBUG][INIT] tag (-t) : pg-meta
[2025-07-13 06:16:05][DEBUG][INIT] key (-k) : pg-meta
[2025-07-13 06:16:05][DEBUG][INIT] encrypt (-e) : false[2025-07-13 06:16:05][DEBUG][INIT] upload (-u) : false[2025-07-13 06:16:05][DEBUG][INIT] remove (-r) : -mmin +1200
[2025-07-13 06:16:05][INFO][LOCK] acquire lock @ /tmp/backup.lock
[2025-07-13 06:16:05][INFO][LOCK] lock acquired success on /tmp/backup.lock, pid=107417[2025-07-13 06:16:05][INFO][BKUP] backup begin, from postgres:/// to /pg/backup/backup_pg-meta_20250713.tar.lz4
[2025-07-13 06:16:05][INFO][BKUP] backup in normal mode
pg_basebackup: initiating base backup, waiting for checkpoint to completepg_basebackup: checkpoint completed
pg_basebackup: write-ahead log start point: 0/7000028 on timeline 1pg_basebackup: write-ahead log end point: 0/7000FD8
pg_basebackup: syncing data to disk ...
pg_basebackup: base backup completed
[2025-07-13 06:16:06][INFO][BKUP] backup complete!
[2025-07-13 06:16:06][INFO][RMBK] remove local obsolete backup: 1200[2025-07-13 06:16:06][INFO][BKUP] find obsolete backups: find /pg/backup/ -maxdepth 1 -type f -mmin +1200 -name 'backup*.lz4'[2025-07-13 06:16:06][WARN][BKUP] remove obsolete backups:
[2025-07-13 06:16:06][INFO][RMBK] remove old backup complete[2025-07-13 06:16:06][INFO][LOCK] release lock @ /tmp/backup.lock
[2025-07-13 06:16:06][INFO][DONE] backup procedure complete!
[2025-07-13 06:16:06][INFO]================================================================
Backup are compressed with lz4, You can unzip and extract the tarball with the following command:
mkdir -p /tmp/data # extract backup to this directorycat /pg/backup/backup_pg-meta_20250713.tar.lz4 | unlz4 -d -c | tar -xC /tmp/data
Logical Backup
You can also use the pg_dump command to perform a logical backup.
Logical backups cannot be used for PITR (Point In Time Recovery),
but they are useful for migrating data between different major versions, or implement flexible data export logic.
Bootstrap from Repo
Now let’s say you have an existing cluster pg-meta, and want to FORK it as pg-meta2:
You’ll need to create the new pg-meta2 cluster fork, then run pitr on it.