pig pgbackrest

Manage pgBackRest backup and restore primitives with pig pgbackrest

The pig pgbackrest command (alias pig pb) manages pgBackRest backups and provides low-level restore primitives. It wraps common pgbackrest operations for a simplified backup management experience. All commands run as the database superuser (default postgres). For orchestrated point-in-time recovery on managed clusters, prefer pig pitr.

pig pb - Manage pgBackRest backup and point-in-time recovery.

Information:
  pig pb info                      show backup info
  pig pb list                      list backups
  pig pb list repo                 list configured repositories
  pig pb list stanza               list all stanzas

Backup & Restore:
  pig pb backup                    create backup (auto: full/incr)
  pig pb backup full               create full backup
  pig pb restore                   low-level restore primitive
  pig pb restore -t "..."          restore to specific time
  pig pb expire                    cleanup expired backups

Stanza Management:
  pig pb create                    create stanza (first-time setup)
  pig pb upgrade                   upgrade stanza (after PG upgrade)
  pig pb delete                    delete stanza (DANGEROUS!)

Control:
  pig pb check                     verify backup integrity
  pig pb start                     enable pgBackRest operations
  pig pb stop                      disable pgBackRest operations
  pig pb log                       view pgBackRest logs

Examples:
  pig pb info                      # show all backup info
  pig pb backup                    # auto: full if none, else incr
  pig pb backup full               # full backup
  pig pb restore -d                # restore to latest (end of WAL)
  pig pb restore -t "2025-01-01 12:00:00+08"  # restore to time
  pig pb create                    # initialize stanza
  pig pb expire                    # cleanup per retention policy

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`

Backup & Restore:

Command	Alias	Description	Implementation
`pb backup`	`b`	Create backup	`pgbackrest backup`
`pb restore`	`r`	Low-level restore primitive	`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 (dangerous!)	`pgbackrest stanza-delete`

Control Commands:

Command	Alias	Description	Implementation
`pb check`	`ck`	Verify backup repository integrity	`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

Quick Start

# View backup info
pig pb info                          # Show all backup info
pig pb info -o json                  # Result-wrapped structured JSON output
pig pb info --raw --raw-output json  # Native pgBackRest JSON output
pig pb ls                            # List all backups
pig pb ls repo                       # List configured repos
pig pb ls stanza                     # List all stanzas

# Create backup (must run on primary)
pig pb backup                        # Auto mode: full if none, else incr
pig pb backup full                   # Full backup
pig pb backup diff                   # Differential backup
pig pb backup incr                   # Incremental backup

# Restore (low-level restore primitive, at least one recovery target is required)
pig pb restore -d                    # Restore to latest (end of WAL)
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 --name savepoint      # Restore to named restore point

# Stanza management
pig pb create                        # Initialize stanza
pig pb upgrade                       # Upgrade stanza after PG major upgrade
pig pb check                         # Verify repository integrity

# Cleanup
pig pb expire                        # Clean up per retention policy
pig pb expire --plan                 # Preview cleanup plan only

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`	Database superuser (default: `$PIG_DBSU` or `postgres`)

Stanza Auto-Detection:

If -s is not specified, pig auto-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. Backups can only run on the primary instance.

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)	Auto mode: full if no backup exists, otherwise incremental
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

Primary Check:

Before running a backup, the command automatically checks whether the current instance is primary. If it is a replica, the command exits with an error. Use --force to skip this check.

pb expire

Clean up expired backups and WAL archives according to the retention policy.

pig pb expire                        # Clean up per policy
pig pb expire --set 20250101-*       # Delete a specific backup set
pig pb expire --set 20250101-* -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`

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 from backup with recovery target support. At least one recovery target (-d/-I/-t/--name/--lsn/--xid) must be specified explicitly. Without parameters, help is shown.

# 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 "..." -X           # Exclusive mode (stop before target)
pig pb restore -t "..." --target-action=promote  # Promote after reaching target
pig pb restore -t "..." -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.

Native pgBackRest restore args after -- cannot override recovery targets, lifecycle, data directory, repository, config, or selection semantics already managed by Pig. Use Pig’s first-class options for those semantics. Tablespace/link migration options such as --tablespace-map, --link-map, and --link-all can still be passed through.

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

Important: Stop PostgreSQL before restore. If the PGDATA is managed by Patroni, use pig pitr to orchestrate Patroni, PostgreSQL, and pgBackRest:

pig pg stop                          # Stop PostgreSQL
pig pb restore -t "..."              # Execute restore
pig pg start                         # Start PostgreSQL

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

Warning: This is a destructive and irreversible operation. All backups will be permanently deleted.

The command includes multiple safety mechanisms:

In text mode, it requires interactive y/yes confirmation unless --yes is specified
Structured output mode requires explicit --yes
If the config file contains multiple stanzas and --stanza is not specified, pig refuses to auto-select a deletion target

Control Commands

pb check

Verify backup repository integrity and configuration.

pig pb check                         # Verify repository

This command checks:

WAL archive configuration correctness
Repository accessibility
Stanza configuration validity

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	Makes parent command `pb log` follow; no-op in `pb log tail` because tail always follows

Permission Handling:

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

Design Notes

Command Execution:

All pig pb commands run as the database superuser (DBSU), because pgBackRest needs access to PostgreSQL data files and WAL archives.

Execution logic:

If the current user is DBSU: execute directly
If the current user is root: use su - postgres -c "..." to execute
Other users: use sudo -inu postgres -- ... to execute

Relationship with pgbackrest:

pig pb is not a complete wrapper for pgbackrest; it is a higher-level abstraction for common operations:

Auto-detect stanza name without specifying it every time
Auto-check primary role before backup
Show restore plan and require interactive y/yes confirmation before restore
Provide user-friendly time format input
Provide post-restore guidance

For full pgbackrest functionality, use the pgbackrest command directly.

Default Configuration Paths:

Config	Default
Config file	`/etc/pgbackrest/pgbackrest.conf`
Log directory	`/pg/log/pgbackrest`
Data directory	`pg1-path` from config, or `$PGDATA`, or `/pg/data`

Security Considerations:

pb delete requires interactive y/yes confirmation when --yes is not specified, and --stanza must be explicit under multi-stanza configs
pb restore requires an explicit recovery target, validates --time, and requires interactive y/yes confirmation when --yes is not specified
pb backup checks primary role by default to prevent running on a replica
pb log tail does not support structured output; use pb log show -n N -o json when a JSONL snapshot is required

Platform Support:

This command is designed for Linux systems and depends on Pigsty’s default directory layout.

pig pgbackrest

Command Overview

Quick Start

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

Design Notes

Was this page helpful?