pig pgbackrest

Create, inspect, restore, and expire pgBackRest backups

pig pgbackrest (alias pig pb) creates backups, restores data, and manages pgBackRest stanzas. It runs pgBackRest as the PostgreSQL operating-system user, selected by --dbsu or $PIG_DBSU (default postgres).

Before the first backup, install pgBackRest and configure the stanza and repository in pgbackrest.conf. A stanza groups the backup configuration for one PostgreSQL cluster. In PostgreSQL, enable archive_mode and set archive_command to call pgBackRest.

Use pig pitr when recovery must also stop Patroni and PostgreSQL, then restart PostgreSQL. Use pig pb restore when you manage those steps yourself.

Command Overview

Information Query:

Command	Alias	Description	Implementation
`pb info`	`i`	Show backup repository info	`pgbackrest info`
`pb list`	`ls`	List backup sets, repos, and stanzas	`pgbackrest info` and configuration

Backup & Restore:

Command	Alias	Description	Implementation
`pb backup`	`b`	Create backup	`pgbackrest backup`
`pb restore`	`r`	Restore backup files	`pgbackrest restore`
`pb expire`	`e`	Clean up expired backups	`pgbackrest expire`

Stanza Management:

Command	Alias	Description	Implementation
`pb create`	`c`	Create stanza (first-time setup)	`pgbackrest stanza-create`
`pb upgrade`	`u`	Upgrade stanza after PG major upgrade	`pgbackrest stanza-upgrade`
`pb delete`	`d`	Delete stanza and its backups	`pgbackrest stanza-delete`

Control Commands:

Command	Alias	Description	Implementation
`pb check`	`ck`	Check stanza configuration and WAL archiving	`pgbackrest check`
`pb start`	`up`	Enable pgBackRest operations	`pgbackrest start`
`pb stop`	`dw`	Disable pgBackRest operations	`pgbackrest stop`
`pb log`	`l`	View logs	latest log snapshot / tail

Create the first backup

After configuring pgBackRest and WAL archiving, create the stanza and check the configuration:

pig pb create
pig pb check

If the check succeeds, create a full backup and inspect it:

pig pb backup full
pig pb info

Global Options

These options apply to all pig pb subcommands:

Option	Short	Description
`--stanza`	`-s`	pgBackRest stanza name (auto-detected)
`--config`	`-c`	Config file path
`--repo`	`-r`	Repository number (multi-repo scenario)
`--dbsu`	`-U`	PostgreSQL operating-system user (default: `$PIG_DBSU` or `postgres`)

Stanza Auto-Detection:

If -s is not specified, PIG detects the stanza name from the config file:

Read the config file (default /etc/pgbackrest/pgbackrest.conf)
Find sections that do not start with [global*]
Use the first stanza found

If the config file contains multiple stanzas, PIG emits a warning and uses the first one. In that case, specify --stanza explicitly.

Multi-Repo Support:

pgBackRest supports multiple repositories (repo1, repo2, etc.). Use -r to choose the target repository:

pig pb backup -r 1                   # Backup to repo1
pig pb backup -r 2                   # Backup to repo2
pig pb info -r 2                     # View repo2 backup info

Information Commands

pb info

Show detailed backup repository information, including all backup sets and WAL archive status.

pig pb info                          # Show all backup info
pig pb info --raw --raw-output json  # Raw JSON output
pig pb info --set 20250101-120000F   # Show details for a specific backup set

Options:

Option	Short	Description
`--raw`	`-R`	Raw output mode (passes through pgBackRest output)
`--raw-output`		Raw output format: text, json (only in `--raw` mode)
`--set`		Show details for a specific backup set

pb ls

List resources in the backup repository.

pig pb ls                            # List all backups (default)
pig pb ls backup                     # List all backups (explicit)
pig pb ls repo                       # List configured repos
pig pb ls stanza                     # List all stanzas

Types:

Type	Description	Data Source
backup	List all backup sets (default)	pgbackrest info
repo	List configured repos	Parse pgbackrest.conf
stanza	List all stanzas	Parse pgbackrest.conf

Backup Commands

pb backup

Create a physical backup. PIG checks that the local instance is a primary before running pgBackRest.

pig pb backup                        # Auto mode
pig pb backup full                   # Full backup
pig pb backup diff                   # Differential backup
pig pb backup incr                   # Incremental backup
pig pb backup --force                # Skip primary role check

Options:

Option	Short	Description
`--force`	`-f`	Skip primary role check

Backup Types:

Type	Description
(empty)	Use pgBackRest configuration; by default, incremental, or full when no full backup exists
full	Full backup: backup all data
diff	Differential backup: changes since the last full backup
incr	Incremental backup: changes since the last backup of any type

A replica, stopped instance, or unknown role fails this check. Use --force only when you intend to delegate role handling to your pgBackRest configuration. It skips the PIG check; pgBackRest still applies its own backup requirements.

pb expire

Remove backups and WAL archives according to the configured retention policy. Use an exact backup label with --set; this also expires backups that depend on that set. WAL retention still applies during this operation. See the pgBackRest expire reference.

pig pb expire                        # Clean up per policy
pig pb expire --set 20250101-120000F       # Delete a specific backup set
pig pb expire --set 20250101-120000F -y    # Skip confirmation when deleting backup set
pig pb expire --plan                 # Preview cleanup plan only, do not delete

Options:

Option	Short	Description
`--set`		Delete a specific backup set
`--plan`		Preview cleanup plan only, do not delete backups
`--yes`	`-y`	Skip confirmation prompt when used with `--set`

--plan runs a pgBackRest dry run. With structured output, the PIG plan includes the dry-run output when it is available. Review that output to see the affected backups.

Retention Policy:

Retention policy is configured in pgbackrest.conf:

[global]
repo1-retention-full=2               # Full backups to retain
repo1-retention-diff=4               # Differential backups to retain
repo1-retention-archive=2            # WAL archive retention policy

Restore Commands

pb restore

Restore backup files into the target data directory. PostgreSQL must be stopped. Select exactly one recovery target: -d, -I, -t, --name, --lsn, or --xid. A missing target returns an error; text mode also shows help.

# Recovery target (mutually exclusive options)
pig pb restore -d                    # Restore to latest (explicit)
pig pb restore -I                    # Restore to backup consistency point
pig pb restore -t "2025-01-01 12:00:00+08"  # Restore to specific time
pig pb restore -t "2025-01-01"       # Restore to date (00:00:00 that day)
pig pb restore -t "12:00:00"         # Restore to time (today)
pig pb restore --name my-savepoint   # Restore to named restore point
pig pb restore --lsn "0/7C82CB8"     # Restore to LSN
pig pb restore --xid 12345           # Restore to transaction ID

# Backup set selection (must combine with a recovery target)
pig pb restore -b 20251225-120000F -d  # Restore from specific backup set to latest

# Other options
pig pb restore -t "2025-01-01 12:00:00+08" -X           # Exclusive mode (stop before target)
pig pb restore -t "2025-01-01 12:00:00+08" --target-action=promote  # Promote after reaching target
pig pb restore -t "2025-01-01 12:00:00+08" -T current   # Recover along current timeline
pig pb restore -d --plan             # Preview restore plan only
pig pb restore -d -y                 # Skip interactive y/yes confirmation
pig pb restore -d -- --delta         # Pass native pgBackRest restore args after --

Recovery Target Options:

Option	Short	Description
`--default`	`-d`	Restore to end of WAL stream (latest data)
`--immediate`	`-I`	Restore to backup consistency point
`--time`	`-t`	Restore to specific timestamp
`--name`		Restore to named restore point
`--lsn`		Restore to specific LSN
`--xid`		Restore to specific transaction ID

Backup Set and Other Options:

Option	Short	Description
`--set`	`-b`	Restore from a specific backup set (can combine with target)
`--data`	`-D`	Target data directory
`--exclusive`	`-X`	Exclusive mode: stop before target
`--target-action`		Action after reaching recovery target: pause/promote/shutdown
`--target-timeline`	`-T`	Recovery timeline: latest/current/N/0xN
`--plan`		Preview restore plan only, do not execute
`--yes`	`-y`	Skip interactive y/yes confirmation
Native args after `--`		Pass through pgBackRest restore args, for example `-- --delta`

Combination Rules: --target-action cannot be used with --default, because --default already means recovery to the end of the WAL stream. --exclusive/-X must be used with an explicit stop target: --time, --lsn, or --xid.

Set the target, data directory, stanza, repository, and config through PIG options. PIG rejects native arguments that would override them, including --repoN-* and --recovery-option. Pass other restore options after --, for example --delta, --tablespace-map, --link-map, or --link-all. Use -- --delta to restore over an existing data directory with checksum-based file reuse.

Time Formats:

Supports multiple time formats and auto-completes timezones (including non-integer-hour zones such as +05:30):

Format	Example	Description
Full format	`2025-01-01 12:00:00+08`	Complete timestamp with timezone
Date only	`2025-01-01`	Auto-completes to 00:00:00 that day (current timezone)
Time only	`12:00:00`	Auto-completes to today (current timezone)

Restore Flow:

Validate parameters and environment
Check that PostgreSQL is stopped
Show restore plan and wait for interactive y/yes confirmation
Execute pgbackrest restore
Provide post-restore guidance

For a standalone instance at /pg/data, inspect the plan, stop the instance, then restore:

pig pb restore -D /pg/data -t "2025-01-01 12:00:00+08" --plan
pig pg stop -D /pg/data
pig pb restore -D /pg/data -t "2025-01-01 12:00:00+08" -- --delta
pig pg start -D /pg/data
pig pg psql -D /pg/data

For another path, pass the same -D to each command. Verify the recovered data before promotion. When Patroni is active for the managed directory, pb restore refuses the operation; use pig pitr.

Text mode asks for y or yes before restore. In scripts with -o json or -o yaml, add --yes to execute, or use --plan to inspect the operation.

Stanza Management Commands

pb create

Initialize a new stanza. Must run before the first backup.

pig pb create                        # Create stanza
pig pb create --no-online            # Create when PostgreSQL is not running
pig pb create --force                # Force create

Options:

Option	Short	Description
`--no-online`		Create when PostgreSQL is not running
`--force`	`-f`	Force create

pb upgrade

Update stanza after a PostgreSQL major version upgrade.

pig pb upgrade                       # Upgrade stanza
pig pb upgrade --no-online           # Upgrade when PostgreSQL is not running

Options:

Option	Description
`--no-online`	Upgrade when PostgreSQL is not running

Use Case:

After a PostgreSQL major version upgrade (for example, 16 -> 17), run this command to update stanza metadata.

pb delete

Delete a stanza and all its backups.

pig pb delete                        # Delete stanza (interactive y/N confirmation)
pig pb delete --yes                  # Skip interactive y/yes confirmation
pig pb delete --plan                 # Preview delete plan

Options:

Option	Short	Description
`--plan`		Preview delete plan only, do not execute
`--yes`	`-y`	Skip interactive y/yes confirmation

Deletion permanently removes the selected stanza’s backups. In text mode, enter y or yes to confirm, or use --yes. Structured execution requires --yes. When the configuration has several stanzas, select one with --stanza.

Control Commands

pb check

Check stanza configuration, repository access, and WAL archiving.

pig pb check                         # Check configuration and archiving

This command checks:

WAL archive configuration correctness
Repository accessibility
Stanza configuration validity

check does not read every backup file to verify its contents. Use pgBackRest verify when you need backup and archive checksum verification.

pb start

Enable pgBackRest operations.

pig pb start                         # Enable operations

Use this command after pb stop to resume normal operations.

pb stop

Disable pgBackRest operations for maintenance.

pig pb stop                          # Disable operations
pig pb stop --force                  # Terminate running operations

Options:

Option	Short	Description
`--force`	`-f`	Terminate running operations

Use Case:

Use this command during system maintenance to prevent new backup operations from starting.

Log Commands

pb log

View pgBackRest log files. The log directory is read from pgBackRest config log-path first, and falls back to /pg/log/pgbackrest/ when not configured. The parent command shows the latest log snapshot by default; use tail or -f for live follow. Only pb log and pb log show support -o json JSONL output; log snapshots do not support yaml or json-pretty, and follow/tail does not support structured output.

pig pb log                           # Show latest log lines
pig pb log list                      # List log files
pig pb log tail                      # Real-time view latest log
pig pb log tail -n 100               # Show last 100 lines and follow
pig pb log show                      # Show latest log content
pig pb log show -n 50                # Show last 50 lines
pig pb log cat                       # Alias for show

Subcommands:

Subcommand	Aliases	Description
list	ls	List log files
show	cat, c	Show latest log content
tail	t, f, follow	Real-time follow latest log

Options:

Option	Short	Default	Description
`--lines`	`-n`	50	Number of lines to show
`--follow`	`-f`	false	Follow with `pb log`; `pb log tail` always follows

Permission Handling:

If the current user does not have permission to read the log directory, the command automatically retries with sudo.

Paths and privileges

Setting	Default
Configuration file	`/etc/pgbackrest/pgbackrest.conf`
Log directory	Configured `log-path`, then `/pg/log/pgbackrest`
Restore data directory	`--data`, configured `pg1-path`, `$PGDATA`, then `/pg/data`

PIG runs pgBackRest directly when the current user is the selected database operating-system user. From root, it uses su; from another account, it uses sudo -H -u. The user must be able to read the configuration and access the data and repository paths.

These commands use Linux and Pigsty defaults. Set the configuration path and stanza explicitly for other layouts. For pgBackRest operations without a PIG command, run pgbackrest directly.

Design record

PIG’s Operations CLI Safety Contract explains the boundary between the low-level pb restore primitive and the orchestrated pig pitr workflow.

pig pgbackrest

Command Overview

Create the first backup

Global Options

Information Commands

pb info

pb ls

Backup Commands

pb backup

pb expire

Restore Commands

pb restore

Stanza Management Commands

pb create

pb upgrade

pb delete

Control Commands

pb check

pb start

pb stop

Log Commands

pb log

Paths and privileges

Design record

Was this page helpful?