user-guide-rhel.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head>
<title>pgBackRest User Guide - RHEL
</title><meta http-equiv="Content-Type" content="text/html;charset=utf-8"></meta>
<meta property="og:site_name" content="pgBackRest - Reliable PostgreSQL Backup &amp; Restore"></meta>
<meta property="og:title" content="pgBackRest User Guide - RHEL"></meta>
<meta property="og:type" content="website"></meta>
<link rel="icon" href="favicon.png" type="image/png"></link>
<meta property="og:image:type" content="image/png"></meta>
<meta property="og:image" content="http://www.pgbackrest.org/logo.png"></meta>
<meta name="description" content="The pgBackRest User Guide demonstrates how to quickly and easily setup pgBackRest for your PostgreSQL database. Step-by-step instructions lead the user through all the important features of the fastest, most reliable PostgreSQL backup and restore solution."></meta>
<meta property="og:description" content="The pgBackRest User Guide demonstrates how to quickly and easily setup pgBackRest for your PostgreSQL database. Step-by-step instructions lead the user through all the important features of the fastest, most reliable PostgreSQL backup and restore solution."></meta>
<link rel="stylesheet" href="default.css" type="text/css"></link>
<script async src="https://www.googletagmanager.com/gtag/js?id=G-VKCRNV73H1"></script>
<script>window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}gtag('js',new Date());gtag('config','G-VKCRNV73H1');</script>
</head><body><div class="page-header"><div class="page-header-title">
pgBackRest User Guide
</div><div class="page-header-subtitle">
RHEL
</div></div><div class="page-menu"><div class="menu-body"><div class="menu"><a class="menu-link" href="/">
Home
</a></div><div class="menu"><a class="menu-link" href="user-guide-index.html">
User Guides
</a></div><div class="menu"><a class="menu-link" href="release.html">
Releases
</a></div><div class="menu"><a class="menu-link" href="configuration.html">
Configuration
</a></div><div class="menu"><a class="menu-link" href="command.html">
Commands
</a></div><div class="menu"><a class="menu-link" href="faq.html">
FAQ
</a></div><div class="menu"><a class="menu-link" href="metric.html">
Metrics
</a></div></div></div><div class="page-toc"><div class="page-toc-header"><div class="page-toc-title">
Table of Contents
</div></div><div class="page-toc-body"><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#introduction">
Introduction
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#concept">
Concepts
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#concept/backup">
Backup
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#concept/restore">
Restore
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#concept/wal">
Write Ahead Log (WAL)
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#concept/encryption">
Encryption
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#upgrading">
Upgrading pgBackRest
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#upgrading/v1-v2">
Upgrading pgBackRest from v1 to v2
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#upgrading/v2.x">
Upgrading pgBackRest from v2.x to v2.y
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#build">
Build
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#installation">
Installation
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#quickstart">
Quick Start
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/setup-demo-cluster">
Setup Demo Cluster
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/configure-stanza">
Configure Cluster Stanza
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/create-repository">
Create the Repository
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/configure-archiving">
Configure Archiving
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/retention">
Configure Retention
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/configure-encryption">
Configure Repository Encryption
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/create-stanza">
Create the Stanza
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/check-configuration">
Check the Configuration
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/performance-tuning">
Performance Tuning
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/perform-backup">
Perform a Backup
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/schedule-backup">
Schedule a Backup
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/backup-info">
Backup Information
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#quickstart/perform-restore">
Restore a Backup
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#monitor">
Monitoring
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#monitor/postgresql">
In <span class="postgres">PostgreSQL</span>
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#backup">
Backup
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#backup/bundle">
File Bundling
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#backup/block">
Block Incremental
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#backup/annotate">
Backup Annotations
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#retention">
Retention
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#retention/full">
Full Backup Retention
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#retention/diff">
Differential Backup Retention
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#retention/archive">
Archive Retention
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#restore">
Restore
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#restore/ownership">
File Ownership
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#restore/option-delta">
Delta Option
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#restore/option-db-include">
Restore Selected Databases
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#pitr">
Point-in-Time Recovery
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#delete-stanza">
Delete a Stanza
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#multi-repo">
Multiple Repositories
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#azure-support">
Azure-Compatible Object Store Support
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#s3-support">
S3-Compatible Object Store Support
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#sftp-support">
SFTP Support
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#gcs-support">
GCS-Compatible Object Store Support
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#repo-target-time">
Target Time for Repository
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#repo-host">
Dedicated Repository Host
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#repo-host/install">
Installation
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#repo-host/config">
Configuration
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#repo-host/setup-tls">
Setup TLS Server
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#repo-host/stanza-create">
Create and Check Stanza
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#repo-host/perform-backup">
Perform a Backup
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#repo-host/perform-restore">
Restore a Backup
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#parallel-backup-restore">
Parallel Backup / Restore
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#start-stop">
Starting and Stopping
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#replication">
Replication
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#replication/installation">
Installation
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#replication/hot-standby">
Hot Standby
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#replication/streaming">
Streaming Replication
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#multi-stanza">
Multiple Stanzas
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#multi-stanza/installation">
Installation
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#multi-stanza/configuration">
Configuration
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#multi-stanza/setup-demo-cluster">
Setup Demo Cluster
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#multi-stanza/create-stanza">
Create the Stanza and Check Configuration
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#async-archiving">
Asynchronous Archiving
</a></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#async-archiving/async-archive-push">
Archive Push
</a></div></div><div class="section2-toc"><div class="section2-toc-number"></div><div class="section2-toc-title"><a href="#async-archiving/async-archive-get">
Archive Get
</a></div></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#standby-backup">
Backup from a Standby
</a></div></div><div class="section1-toc"><div class="section1-toc-number"></div><div class="section1-toc-title"><a href="#upgrade-stanza">
Upgrading <span class="postgres">PostgreSQL</span>
</a></div></div></div></div><div class="page-body"><div class="section1"><a id="introduction"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Introduction
</div></div><div class="section-body"><div class="section-body-text">
This user guide is intended to be followed sequentially from beginning to end &mdash; each section depends on the last. For example, the <a href="#restore">Restore</a> section relies on setup that is performed in the <a href="#quickstart">Quick Start</a> section. Once <span class="backrest">pgBackRest</span> is up and running then skipping around is possible but following the user guide in order is recommended the first time through.
</div><div class="section-body-text">
Although the examples in this guide are targeted at <span class="host">RHEL</span> and <span class="postgres">PostgreSQL</span> 13, it should be fairly easy to apply the examples to any Unix distribution and <span class="postgres">PostgreSQL</span> version. The only OS-specific commands are those to create, start, stop, and drop <span class="postgres">PostgreSQL</span> clusters. The <span class="backrest">pgBackRest</span> commands will be the same on any Unix system though the location of the executable may vary. While <span class="backrest">pgBackRest</span> strives to operate consistently across versions of <span class="postgres">PostgreSQL</span>, there are subtle differences between versions of <span class="postgres">PostgreSQL</span> that may show up in this guide when illustrating certain examples, e.g. <span class="postgres">PostgreSQL</span> path/file names and settings.
</div><div class="section-body-text">
Configuration information and documentation for PostgreSQL can be found in the <span class="postgres">PostgreSQL</span> <a href="http://www.postgresql.org/docs/13/static/index.html">Manual</a>.
</div><div class="section-body-text">
A somewhat novel approach is taken to documentation in this user guide. Each command is run on a virtual machine when the documentation is built from the XML source. This means you can have a high confidence that the commands work correctly in the order presented. Output is captured and displayed below the command when appropriate. If the output is not included it is because it was deemed not relevant or was considered a distraction from the narrative.
</div><div class="section-body-text">
All commands are intended to be run as an unprivileged user that has sudo privileges for both the <span class="user">root</span> and <span class="user">postgres</span> users. It's also possible to run the commands directly as their respective users without modification and in that case the <span class="cmd">sudo</span> commands can be stripped off.
</div></div></div><div class="section1"><a id="concept"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Concepts
</div></div><div class="section-body"><div class="section-body-text">
The following concepts are defined as they are relevant to <span class="backrest">pgBackRest</span>, <span class="postgres">PostgreSQL</span>, and this user guide.
</div><div class="section2"><a id="concept/backup"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Backup
</div></div><div class="section-body"><div class="section-body-text">
A backup is a consistent copy of a database cluster that can be restored to recover from a hardware failure, to perform Point-In-Time Recovery, or to bring up a new standby.
</div><div class="section-body-text">
<b>Full Backup</b>: <span class="backrest">pgBackRest</span> copies the entire contents of the database cluster to the backup. The first backup of the database cluster is always a Full Backup. <span class="backrest">pgBackRest</span> is always able to restore a full backup directly. The full backup does not depend on any files outside of the full backup for consistency.
</div><div class="section-body-text">
<b>Differential Backup</b>: <span class="backrest">pgBackRest</span> copies only those database cluster files that have changed since the last full backup. <span class="backrest">pgBackRest</span> restores a differential backup by copying all of the files in the chosen differential backup and the appropriate unchanged files from the previous full backup. The advantage of a differential backup is that it requires less disk space than a full backup, however, the differential backup and the full backup must both be valid to restore the differential backup.
</div><div class="section-body-text">
<b>Incremental Backup</b>: <span class="backrest">pgBackRest</span> copies only those database cluster files that have changed since the last backup (which can be another incremental backup, a differential backup, or a full backup). As an incremental backup only includes those files changed since the prior backup, they are generally much smaller than full or differential backups. As with the differential backup, the incremental backup depends on other backups to be valid to restore the incremental backup. Since the incremental backup includes only those files since the last backup, all prior incremental backups back to the prior differential, the prior differential backup, and the prior full backup must all be valid to perform a restore of the incremental backup. If no differential backup exists then all prior incremental backups back to the prior full backup, which must exist, and the full backup itself must be valid to restore the incremental backup.
</div></div></div><div class="section2"><a id="concept/restore"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Restore
</div></div><div class="section-body"><div class="section-body-text">
A restore is the act of copying a backup to a system where it will be started as a live database cluster. A restore requires the backup files and one or more WAL segments in order to work correctly.
</div></div></div><div class="section2"><a id="concept/wal"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Write Ahead Log (WAL)
</div></div><div class="section-body"><div class="section-body-text">
WAL is the mechanism that <span class="postgres">PostgreSQL</span> uses to ensure that no committed changes are lost. Transactions are written sequentially to the WAL and a transaction is considered to be committed when those writes are flushed to disk. Afterwards, a background process writes the changes into the main database cluster files (also known as the heap). In the event of a crash, the WAL is replayed to make the database consistent.
</div><div class="section-body-text">
WAL is conceptually infinite but in practice is broken up into individual 16MB files called segments. WAL segments follow the naming convention <span class="id">0000000100000A1E000000FE</span> where the first 8 hexadecimal digits represent the timeline and the next 16 digits are the logical sequence number (LSN).
</div></div></div><div class="section2"><a id="concept/encryption"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Encryption
</div></div><div class="section-body"><div class="section-body-text">
Encryption is the process of converting data into a format that is unrecognizable unless the appropriate password (also referred to as passphrase) is provided.
</div><div class="section-body-text">
<span class="backrest">pgBackRest</span> will encrypt the repository based on a user-provided password, thereby preventing unauthorized access to data stored within the repository.
</div></div></div></div></div><div class="section1"><a id="upgrading"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Upgrading pgBackRest
</div></div><div class="section-body"><div class="section2"><a id="upgrading/v1-v2"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Upgrading pgBackRest from v1 to v2
</div></div><div class="section-body"><div class="section-body-text">
Upgrading from <span class="host">v1</span> to <span class="host">v2</span> is fairly straight-forward. The repository format has not changed and all non-deprecated options from <span class="host">v1</span> are accepted, so for most installations it is simply a matter of installing the new version.
</div><div class="section-body-text">
However, there are a few caveats:
</div><ul class="list-unordered"><li class="list-unordered">
The deprecated <span class="br-option">thread-max</span> option is no longer valid. Use <span class="br-option">process-max</span> instead.
</li><li class="list-unordered">
The deprecated <span class="br-option">archive-max-mb</span> option is no longer valid. This has been replaced with the <span class="br-option">archive-push-queue-max</span> option which has different semantics.
</li><li class="list-unordered">
The default for the <span class="br-option">backup-user</span> option has changed from <span class="id">backrest</span> to <span class="id">pgbackrest</span>.
</li><li class="list-unordered">
In <span class="host">v2.02</span> the default location of the <span class="backrest">pgBackRest</span> configuration file has changed from <span class="file">/etc/pgbackrest.conf</span> to <span class="file">/etc/pgbackrest/pgbackrest.conf</span>. If <span class="file">/etc/pgbackrest/pgbackrest.conf</span> does not exist, the <span class="file">/etc/pgbackrest.conf</span> file will be loaded instead, if it exists.
</li></ul><div class="section-body-text">
Many option names have changed to improve consistency although the old names from <span class="host">v1</span> are still accepted. In general, <span class="id">db-*</span> options have been renamed to <span class="id">pg-*</span> and <span class="id">backup-*</span>/<span class="id">retention-*</span> options have been renamed to <span class="id">repo-*</span> when appropriate.
</div><div class="section-body-text">
<span class="postgres">PostgreSQL</span> and repository options must be indexed when using the new names introduced in <span class="host">v2</span>, e.g. <span class="br-option">pg1-host</span>, <span class="br-option">pg1-path</span>, <span class="br-option">repo1-path</span>, <span class="br-option">repo1-type</span>, etc.
</div></div></div><div class="section2"><a id="upgrading/v2.x"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Upgrading pgBackRest from v2.x to v2.y
</div></div><div class="section-body"><div class="section-body-text">
Upgrading from <span class="host">v2.x</span> to <span class="host">v2.y</span> is straight-forward. The repository format has not changed, so for most installations it is simply a matter of installing binaries for the new version. It is also possible to downgrade if you have not used new features that are unsupported by the older version.
</div><div class="admonition"><div class="important">
IMPORTANT:
</div><div class="important-text">
The local and remote <span class="backrest">pgBackRest</span> versions must match exactly so they should be upgraded together. If there is a mismatch, WAL archiving and backups will not function until the versions match. In such a case, the following error will be reported: <span class="id">[ProtocolError] expected value '2.x' for greeting key 'version' but got '2.y'</span>.
</div></div></div></div></div></div><div class="section1"><a id="build"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Build
</div></div><div class="section-body"><div class="section-body-text">
Installing <span class="backrest">pgBackRest</span> from a package is preferable to building from source. See <a href="#installation">Installation</a> for more information about packages.
</div><div class="section-body-text">
When building from source it is best to use a build host rather than building on production. Many of the tools required for the build should generally not be installed in production. <span class="backrest">pgBackRest</span> consists of a single executable so it is easy to copy to a new host once it is built.
</div><div class="execute"><div class="execute-title">
<span class="host">build</span> <b>&#x21d2;</b> Download version <span class="id">2.55.0</span> of <span class="backrest">pgBackRest</span> to <span class="path">/build</span> path
</div><div class="execute-body">
<pre class="execute-body-cmd">mkdir -p /build</pre>
<pre class="execute-body-cmd">wget -q -O - \
       https://github.com/pgbackrest/pgbackrest/archive/release/2.55.0.tar.gz | \
       tar zx -C /build</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">build</span> <b>&#x21d2;</b> Install build dependencies
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo yum install meson gcc postgresql13-devel openssl-devel \
       libxml2-devel lz4-devel libzstd-devel bzip2-devel libyaml-devel libssh2-devel</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">build</span> <b>&#x21d2;</b> Configure and compile <span class="backrest">pgBackRest</span>
</div><div class="execute-body">
<pre class="execute-body-cmd">meson setup /build/pgbackrest /build/pgbackrest-release-2.55.0</pre>
<pre class="execute-body-cmd">ninja -C /build/pgbackrest</pre>
</div></div></div></div><div class="section1"><a id="installation"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Installation
</div></div><div class="section-body"><div class="section-body-text">
A new host named <span class="host">pg-primary</span> is created to contain the demo cluster and run <span class="backrest">pgBackRest</span> examples.
</div><div class="section-body-text">
Installing <span class="backrest">pgBackRest</span> from a package is preferable to building from source. When installing from a package the rest of the instructions in this section are generally not required, but it is possible that a package will skip creating one of the directories or apply incorrect permissions. In that case it may be necessary to manually create directories or update permissions.
</div><div class="section-body-text">
RHEL packages for <span class="backrest">pgBackRest</span> are available from <a href="http://www.crunchydata.com">Crunchy Data</a> or <a href="http://yum.postgresql.org">yum.postgresql.org</a>.
</div><div class="section-body-text">
If packages are not provided for your distribution/version you can <a href="#build">build from source</a> and then install manually as shown here.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Install dependencies
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo yum install postgresql-libs libssh2</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Copy <span class="backrest">pgBackRest</span> binary from build host
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo scp build:/build/pgbackrest/src/pgbackrest /usr/bin</pre>
<pre class="execute-body-cmd">sudo chmod 755 /usr/bin/pgbackrest</pre>
</div></div><div class="section-body-text">
<span class="backrest">pgBackRest</span> requires log and configuration directories and a configuration file.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create <span class="backrest">pgBackRest</span> configuration file and directories
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo mkdir -p -m 770 /var/log/pgbackrest</pre>
<pre class="execute-body-cmd">sudo chown postgres:postgres /var/log/pgbackrest</pre>
<pre class="execute-body-cmd">sudo mkdir -p /etc/pgbackrest</pre>
<pre class="execute-body-cmd">sudo mkdir -p /etc/pgbackrest/conf.d</pre>
<pre class="execute-body-cmd">sudo touch /etc/pgbackrest/pgbackrest.conf</pre>
<pre class="execute-body-cmd">sudo chmod 640 /etc/pgbackrest/pgbackrest.conf</pre>
<pre class="execute-body-cmd">sudo chown postgres:postgres /etc/pgbackrest/pgbackrest.conf</pre>
</div></div><div class="section-body-text">
<span class="backrest">pgBackRest</span> should now be properly installed but it is best to check. If any dependencies were missed then you will get an error when running <span class="backrest">pgBackRest</span> from the command line.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Make sure the installation worked
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest</pre>
<pre class="execute-body-output">pgBackRest 2.55.0 - General help

Usage:
    pgbackrest [options] [command]

Commands:
    annotate        add or modify backup annotation
    archive-get     get a WAL segment from the archive
    archive-push    push a WAL segment to the archive
    backup          backup a database cluster
    check           check the configuration
    expire          expire backups that exceed retention
    help            get help
    info            retrieve information about backups
    repo-get        get a file from a repository
    repo-ls         list files in a repository
    restore         restore a database cluster
    server          pgBackRest server
    server-ping     ping pgBackRest server
    stanza-create   create the required stanza data
    stanza-delete   delete a stanza
    stanza-upgrade  upgrade a stanza
    start           allow pgBackRest processes to run
    stop            stop pgBackRest processes from running
    verify          verify contents of a repository
    version         get version

Use 'pgbackrest help [command]' for more information.</pre>
</div></div></div></div><div class="section1"><a id="quickstart"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Quick Start
</div></div><div class="section-body"><div class="section-body-text">
The Quick Start section will cover basic configuration of <span class="backrest">pgBackRest</span> and <span class="postgres">PostgreSQL</span> and introduce the <span class="cmd">backup</span>, <span class="cmd">restore</span>, and <span class="cmd">info</span> commands.
</div><div class="section2"><a id="quickstart/setup-demo-cluster"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Setup Demo Cluster
</div></div><div class="section-body"><div class="section-body-text">
Creating the demo cluster is optional but is strongly recommended, especially for new users, since the example commands in the user guide reference the demo cluster; the examples assume the demo cluster is running on the default port (i.e. 5432). The cluster will not be started until a later section because there is still some configuration to do.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres /usr/pgsql-13/bin/initdb \
       -D /var/lib/pgsql/13/data -k -A peer</pre>
</div></div><div class="section-body-text">
By default RHEL includes the day of the week in the log filename. This makes the user guide a bit more complicated so the <span class="pg-option">log_filename</span> is set to a constant.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/var/lib/pgsql/13/data/postgresql.conf</span> <b>&#x21d2;</b> Set <span class="pg-option">log_filename</span>
</div><div class="config-body"><div class="config-body-output">
log_filename = 'postgresql.log'
</div></div></div></div></div><div class="section2"><a id="quickstart/configure-stanza"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Configure Cluster Stanza
</div></div><div class="section-body"><div class="section-body-text">
A stanza is the configuration for a <span class="postgres">PostgreSQL</span> database cluster that defines where it is located, how it will be backed up, archiving options, etc. Most db servers will only have one <span class="postgres">PostgreSQL</span> database cluster and therefore one stanza, whereas backup servers will have a stanza for every database cluster that needs to be backed up.<br/>
<br/>
It is tempting to name the stanza after the primary cluster but a better name describes the databases contained in the cluster. Because the stanza name will be used for the primary and all replicas it is more appropriate to choose a name that describes the actual function of the cluster, such as app or dw, rather than the local cluster name, such as main or prod.
</div><div class="section-body-text">
The name 'demo' describes the purpose of this cluster accurately so that will also make a good stanza name.
</div><div class="section-body-text">
<span class="backrest">pgBackRest</span> needs to know where the base data directory for the <span class="postgres">PostgreSQL</span> cluster is located. The path can be requested from <span class="postgres">PostgreSQL</span> directly but in a recovery scenario the <span class="postgres">PostgreSQL</span> process will not be available. During backups the value supplied to <span class="backrest">pgBackRest</span> will be compared against the path that <span class="postgres">PostgreSQL</span> is running on and they must be equal or the backup will return an error. Make sure that <span class="br-option">pg-path</span> is exactly equal to <span class="pg-option">data_directory</span> as reported by <span class="postgres">PostgreSQL</span>.
</div><div class="section-body-text">
By default RHEL stores clusters in <span class="path">/var/lib/pgsql/[version]/data</span> so it is easy to determine the correct path for the data directory.
</div><div class="section-body-text">
When creating the <span class="file">/etc/pgbackrest/pgbackrest.conf</span> file, the database owner (usually <span class="id">postgres</span>) must be granted read privileges.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure the <span class="postgres">PostgreSQL</span> cluster data directory
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data
</div></div></div><div class="section-body-text">
<span class="backrest">pgBackRest</span> configuration files follow a Windows INI-like convention. Sections are denoted by text in brackets and key/value pairs are contained in each section. Lines beginning with <span class="id">#</span> are ignored and can be used as comments. Quoting is not supported and whitespace is trimmed from keys and values. Sections will be merged if they appear more than once.
</div><div class="section-body-text">
There are multiple ways the <span class="backrest">pgBackRest</span> configuration files can be loaded:
</div><ul class="list-unordered"><li class="list-unordered">
<span class="br-option">config</span> and <span class="br-option">config-include-path</span> are default: the default config file will be loaded, if it exists, and <span class="file">*.conf</span> files in the default config include path will be appended, if they exist.
</li><li class="list-unordered">
<span class="br-option">config</span> option is specified: only the specified config file will be loaded and is expected to exist.
</li><li class="list-unordered">
<span class="br-option">config-include-path</span> is specified: <span class="file">*.conf</span> files in the config include path will be loaded and the path is required to exist. The default config file will be be loaded if it exists. If it is desirable to load only the files in the specified config include path, then the <span class="br-option">--no-config</span> option can also be passed.
</li><li class="list-unordered">
<span class="br-option">config</span> and <span class="br-option">config-include-path</span> are specified: using the user-specified values, the config file will be loaded and <span class="file">*.conf</span> files in the config include path will be appended. The files are expected to exist.
</li><li class="list-unordered">
<span class="br-option">config-path</span> is specified: this setting will override the base path for the default location of the config file and/or the base path of the default config-include-path setting unless the config and/or config-include-path option is explicitly set.
</li></ul><div class="section-body-text">
Files are concatenated as if they were one big file and each file must be valid individually. This means sections must be specified in each file where they are needed to store a key/value. Order doesn't matter but there is precedence based on sections. The precedence (highest to lowest) is:
</div><ul class="list-unordered"><li class="list-unordered">
[<i>stanza</i>:<i>command</i>]
</li><li class="list-unordered">
[<i>stanza</i>]
</li><li class="list-unordered">
[global:<i>command</i>]
</li><li class="list-unordered">
[global]
</li></ul><div class="admonition"><div class="note">
NOTE:
</div><div class="note-text">
<span class="br-option">--config</span>, <span class="br-option">--config-include-path</span> and <span class="br-option">--config-path</span> are command-line only options.
</div></div><div class="section-body-text">
<span class="backrest">pgBackRest</span> can also be configured using environment variables as described in the <a href="command.html">command reference</a>.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Configure <span class="br-option">log-path</span> using the environment
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres bash -c ' \
       export PGBACKREST_LOG_PATH=/path/set/by/env &amp;&amp; \
       pgbackrest --log-level-console=error help backup log-path'</pre>
<pre class="execute-body-output">pgBackRest 2.55.0 - 'backup' command - 'log-path' option help

Path where log files are stored.

The log path provides a location for pgBackRest to store log files. Note that
if log-level-file=off then no log path is required.
</pre>
<pre class="execute-body-output-highlight">current: /path/set/by/env</pre>
<pre class="execute-body-output">default: /var/log/pgbackrest</pre>
</div></div></div></div><div class="section2"><a id="quickstart/create-repository"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Create the Repository
</div></div><div class="section-body"><div class="section-body-text">
The repository is where <span class="backrest">pgBackRest</span> stores backups and archives WAL segments.<br/>
<br/>
It may be difficult to estimate in advance how much space you'll need. The best thing to do is take some backups then record the size of different types of backups (full/incr/diff) and measure the amount of WAL generated per day. This will give you a general idea of how much space you'll need, though of course requirements will likely change over time as your database evolves.
</div><div class="section-body-text">
For this demonstration the repository will be stored on the same host as the <span class="postgres">PostgreSQL</span> server. This is the simplest configuration and is useful in cases where traditional backup software is employed to backup the database host.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create the <span class="backrest">pgBackRest</span> repository
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo mkdir -p /var/lib/pgbackrest</pre>
<pre class="execute-body-cmd">sudo chmod 750 /var/lib/pgbackrest</pre>
<pre class="execute-body-cmd">sudo chown postgres:postgres /var/lib/pgbackrest</pre>
</div></div><div class="section-body-text">
The repository path must be configured so <span class="backrest">pgBackRest</span> knows where to find it.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure the <span class="backrest">pgBackRest</span> repository path
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-path=/var/lib/pgbackrest
</div></div></div><div class="section-body-text">
Multiple repositories may also be configured. See <a href="#multi-repo">Multiple Repositories</a> for details.
</div></div></div><div class="section2"><a id="quickstart/configure-archiving"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Configure Archiving
</div></div><div class="section-body"><div class="section-body-text">
Backing up a running <span class="postgres">PostgreSQL</span> cluster requires WAL archiving to be enabled. Note that <i>at least</i> one WAL segment will be created during the backup process even if no explicit writes are made to the cluster.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/var/lib/pgsql/13/data/postgresql.conf</span> <b>&#x21d2;</b> Configure archive settings
</div><div class="config-body"><div class="config-body-output">
archive_command = 'pgbackrest --stanza=demo archive-push %p'<br/>
archive_mode = on<br/>
log_filename = 'postgresql.log'<br/>
max_wal_senders = 3<br/>
wal_level = replica
</div></div></div><div class="section-body-text">
<span class="id">%p</span> is how <span class="postgres">PostgreSQL</span> specifies the location of the WAL segment to be archived. Setting <span class="pg-option">wal_level</span> to at least <span class="pg-setting">replica</span> and increasing <span class="pg-option">max_wal_senders</span> is a good idea even if there are currently no replicas as this will allow them to be added later without restarting the primary cluster.
</div><div class="section-body-text">
The <span class="postgres">PostgreSQL</span> cluster must be restarted after making these changes and before performing a backup.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Restart the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl restart postgresql-13.service</pre>
</div></div><div class="section-body-text">
When archiving a WAL segment is expected to take more than 60 seconds (the default) to reach the <span class="backrest">pgBackRest</span> repository, then the <span class="backrest">pgBackRest</span> <span class="br-option">archive-timeout</span> option should be increased. Note that this option is not the same as the <span class="postgres">PostgreSQL</span> <span class="pg-option">archive_timeout</span> option which is used to force a WAL segment switch; useful for databases where there are long periods of inactivity. For more information on the <span class="postgres">PostgreSQL</span> <span class="pg-option">archive_timeout</span> option, see <span class="postgres">PostgreSQL</span> <a href="https://www.postgresql.org/docs/current/static/runtime-config-wal.html">Write Ahead Log</a>.
</div><div class="section-body-text">
The <span class="cmd">archive-push</span> command can be configured with its own options. For example, a lower compression level may be set to speed archiving without affecting the compression used for backups.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Config <span class="cmd">archive-push</span> to use a lower compression level
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-path=/var/lib/pgbackrest<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div><div class="section-body-text">
This configuration technique can be used for any command and can even target a specific stanza, e.g. <span class="id">demo:archive-push</span>.
</div></div></div><div class="section2"><a id="quickstart/retention"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Configure Retention
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> expires backups based on retention options.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure retention to 2 full backups
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-full=2<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div><div class="section-body-text">
More information about retention can be found in the <a href="#retention">Retention</a> section.
</div></div></div><div class="section2"><a id="quickstart/configure-encryption"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Configure Repository Encryption
</div></div><div class="section-body"><div class="section-body-text">
The repository will be configured with a cipher type and key to demonstrate encryption. Encryption is always performed client-side even if the repository type (e.g. <span class="host">S3</span> or other object store) supports encryption.
</div><div class="section-body-text">
It is important to use a long, random passphrase for the cipher key. A good way to generate one is to run: <span class="id">openssl rand -base64 48</span>.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="backrest">pgBackRest</span> repository encryption
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO<br/>
repo1-cipher-type=aes-256-cbc<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-full=2<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div><div class="section-body-text">
Once the repository has been configured and the stanza created and checked, the repository encryption settings cannot be changed.
</div></div></div><div class="section2"><a id="quickstart/create-stanza"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Create the Stanza
</div></div><div class="section-body"><div class="section-body-text">
The <span class="cmd">stanza-create</span> command must be run to initialize the stanza. It is recommended that the <span class="cmd">check</span> command be run after <span class="cmd">stanza-create</span> to ensure archiving and backups are properly configured.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create the stanza and check the configuration
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stanza-create</pre>
<pre class="execute-body-output">P00   INFO: stanza-create command begin 2.55.0: --exec-id=1132-b904d6ef --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --stanza=demo
P00   INFO: stanza-create for stanza 'demo' on repo1</pre>
<pre class="execute-body-output-highlight">P00   INFO: stanza-create command end: completed successfully</pre>
</div></div></div></div><div class="section2"><a id="quickstart/check-configuration"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Check the Configuration
</div></div><div class="section-body"><div class="section-body-text">
The <span class="cmd">check</span> command validates that <span class="backrest">pgBackRest</span> and the <span class="pg-setting">archive_command</span> setting are configured correctly for archiving and backups for the specified stanza. It will attempt to check all repositories and databases that are configured for the host on which the command is run. It detects misconfigurations, particularly in archiving, that result in incomplete backups because required WAL segments did not reach the archive. The command can be run on the <span class="postgres">PostgreSQL</span> or repository host. The command may also be run on the standby host, however, since <span class="id">pg_switch_xlog()</span>/<span class="id">pg_switch_wal()</span> cannot be performed on the standby, the command will only test the repository configuration.<br/>
<br/>
Note that <span class="id">pg_create_restore_point('pgBackRest Archive Check')</span> and <span class="id">pg_switch_xlog()</span>/<span class="id">pg_switch_wal()</span> are called to force <span class="postgres">PostgreSQL</span> to archive a WAL segment.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Check the configuration
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --log-level-console=info check</pre>
<pre class="execute-body-output">P00   INFO: check command begin 2.55.0: --exec-id=1159-e5a4570b --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --stanza=demo
P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)</pre>
<pre class="execute-body-output-highlight">P00   INFO: WAL segment 000000010000000000000001 successfully archived to '/var/lib/pgbackrest/archive/demo/13-1/0000000100000000/000000010000000000000001-422bb25a2f87163142f34c61d8545fb377c1275f.gz' on repo1</pre>
<pre class="execute-body-output">P00   INFO: check command end: completed successfully</pre>
</div></div></div></div><div class="section2"><a id="quickstart/performance-tuning"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Performance Tuning
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> has a number of performance options that are not enabled by default to maintain backward compatibility in the repository. However, when creating a new repository the following options are recommended. They can also be used on an existing repository with the caveat that older versions of <span class="backrest">pgBackRest</span> will not be able to read the repository. This incompatibility depends on when the feature was introduced, which will be noted in the list below.
</div><ul class="list-unordered"><li class="list-unordered">
<span class="br-option">compress-type</span> - determines the compression algorithm used by the <span class="cmd">backup</span> and <span class="cmd">archive-push</span> commands. The default is <span class="id">gz</span> (Gzip) but <span class="id">zst</span> (Zstandard) is recommended because it is much faster and provides compression similar to <span class="id">gz</span>. <span class="id">zst</span> has been supported by the <span class="br-option">compress-type</span> option since <a href="release.html#2.27">v2.27</a>. See <a href="configuration.html#section-general/option-compress-type">Compress Type</a> for more details.
</li><li class="list-unordered">
<span class="br-option">repo-bundle</span> - combines small files during backup to save space and improve the speed of both the <span class="cmd">backup</span> and <span class="cmd">restore</span> commands, especially on object stores such as S3. The <span class="br-option">repo-bundle</span> option was introduced in <a href="release.html#2.39">v2.39</a>. See <a href="#backup/bundle">File Bundling</a> for more details.
</li><li class="list-unordered">
<span class="br-option">repo-block</span> - stores only the portions of files that have changed rather than the entire file during <span class="id">diff</span>/<span class="id">incr</span> <span class="cmd">backup</span>. This saves space and increases the speed of the <span class="cmd">backup</span>. The <span class="br-option">repo-block</span> option was introduced in <a href="release.html#2.46">v2.46</a> but at least <a href="release.html#2.52.1">v2.52.1</a> is recommended. See <a href="#backup/block">Block Incremental</a> for more details.
</li></ul><div class="section-body-text">
There are other performance options that are not enabled by default because they require additional configuration or because the default is safe (but not optimal). These options are available in all v2 versions of <span class="backrest">pgBackRest</span>.
</div><ul class="list-unordered"><li class="list-unordered">
<span class="br-option">process-max</span> - determines how many processes will be used for commands. The default is 1, which is almost never the appropriate value. Each command uses <span class="br-option">process-max</span> differently so refer to each command's documentation for details on usage.
</li><li class="list-unordered">
<span class="br-option">archive-async</span> - archives WAL files to the repository in batch which greatly increases archiving speed. It is not enabled by default because it requires a spool path to be created. See <a href="#async-archiving">Asynchronous Archiving</a> for more details.
</li><li class="list-unordered">
<span class="br-option">backup-standby</span> - performs the backup on a standby rather than the primary to reduce load on the primary. It is not enabled by default because it requires additional configuration and the presence of one or more standby hosts. See <a href="#standby-backup">Backup from a Standby</a> for more details.
</li></ul></div></div><div class="section2"><a id="quickstart/perform-backup"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Perform a Backup
</div></div><div class="section-body"><div class="section-body-text">
By default <span class="backrest">pgBackRest</span> will wait for the next regularly scheduled checkpoint before starting a backup. Depending on the <span class="pg-option">checkpoint_timeout</span> and <span class="pg-option">checkpoint_segments</span> settings in <span class="postgres">PostgreSQL</span> it may be quite some time before a checkpoint completes and the backup can begin. Generally, it is best to set <span class="br-setting">start-fast=y</span> so that the backup starts immediately. This forces a checkpoint, but since backups are usually run once a day an additional checkpoint should not have a noticeable impact on performance. However, on very busy clusters it may be best to pass <span class="br-setting">--start-fast</span> on the command-line as needed.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure backup fast start
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO<br/>
repo1-cipher-type=aes-256-cbc<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-full=2<br/>
start-fast=y<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div><div class="section-body-text">
To perform a backup of the <span class="postgres">PostgreSQL</span> cluster run <span class="backrest">pgBackRest</span> with the <span class="cmd">backup</span> command.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Backup the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo \
       --log-level-console=info backup</pre>
<pre class="execute-body-output">P00   INFO: backup command begin 2.55.0: --exec-id=1230-d6c8d558 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-full=2 --stanza=demo --start-fast</pre>
<pre class="execute-body-output-highlight">P00   WARN: no prior backup exists, incr backup has been changed to full</pre>
<pre class="execute-body-output">P00   INFO: execute non-exclusive backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 000000010000000000000002, lsn = 0/2000028
       [filtered 3 lines of output]
P00   INFO: check archive for segment(s) 000000010000000000000002:000000010000000000000003
P00   INFO: new backup label = 20250421-131256F</pre>
<pre class="execute-body-output-highlight">P00   INFO: full backup size = 23.2MB, file total = 936</pre>
<pre class="execute-body-output">P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.55.0: --exec-id=1230-d6c8d558 --log-level-console=info --no-log-timestamp --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-full=2 --stanza=demo</pre>
</div></div><div class="section-body-text">
By default <span class="backrest">pgBackRest</span> will attempt to perform an incremental backup. However, an incremental backup must be based on a full backup and since no full backup existed <span class="backrest">pgBackRest</span> ran a full backup instead.
</div><div class="section-body-text">
The <span class="br-option">type</span> option can be used to specify a full or differential backup.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Differential backup of the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --type=diff \
       --log-level-console=info backup</pre>
<pre class="execute-body-output">       [filtered 7 lines of output]
P00   INFO: check archive for segment(s) 000000010000000000000004:000000010000000000000005
P00   INFO: new backup label = 20250421-131256F_20250421-131300D</pre>
<pre class="execute-body-output-highlight">P00   INFO: diff backup size = 9.1KB, file total = 936</pre>
<pre class="execute-body-output">P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.55.0: --exec-id=1289-be2b5ffd --log-level-console=info --no-log-timestamp --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-full=2 --stanza=demo</pre>
</div></div><div class="section-body-text">
This time there was no warning because a full backup already existed. While incremental backups can be based on a full <i>or</i> differential backup, differential backups must be based on a full backup. A full backup can be performed by running the <span class="cmd">backup</span> command with <span class="br-setting">--type=full</span>.
</div><div class="section-body-text">
During an online backup <span class="backrest">pgBackRest</span> waits for WAL segments that are required for backup consistency to be archived. This wait time is governed by the <span class="backrest">pgBackRest</span> <span class="br-option">archive-timeout</span> option which defaults to 60 seconds. If archiving an individual segment is known to take longer then this option should be increased.
</div></div></div><div class="section2"><a id="quickstart/schedule-backup"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Schedule a Backup
</div></div><div class="section-body"><div class="section-body-text">
Backups can be scheduled with utilities such as cron.
</div><div class="section-body-text">
In the following example, two cron jobs are configured to run; full backups are scheduled for 6:30 AM every Sunday with differential backups scheduled for 6:30 AM Monday through Saturday. If this crontab is installed for the first time mid-week, then pgBackRest will run a full backup the first time the differential job is executed, followed the next day by a differential backup.
</div>
<pre class="code-block">#m h   dom mon dow   command
30 06  *   *   0     pgbackrest --type=full --stanza=demo backup
30 06  *   *   1-6   pgbackrest --type=diff --stanza=demo backup</pre>
<div class="section-body-text">
Once backups are scheduled it's important to configure retention so backups are expired on a regular schedule, see <a href="#retention">Retention</a>.
</div></div></div><div class="section2"><a id="quickstart/backup-info"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Backup Information
</div></div><div class="section-body"><div class="section-body-text">
Use the <span class="cmd">info</span> command to get information about backups.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Get info for the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest info</pre>
<pre class="execute-body-output">stanza: demo
    status: ok
    cipher: aes-256-cbc

    db (current)
        wal archive min/max (13): 000000010000000000000001/000000010000000000000005
</pre>
<pre class="execute-body-output-highlight">        full backup: 20250421-131256F</pre>
<pre class="execute-body-output">            timestamp start/stop: 2025-04-21 13:12:56+00 / 2025-04-21 13:12:58+00
            wal start/stop: 000000010000000000000002 / 000000010000000000000003
            database size: 23.2MB, database backup size: 23.2MB
            repo1: backup set size: 2.9MB, backup size: 2.9MB
</pre>
<pre class="execute-body-output-highlight">        diff backup: 20250421-131256F_20250421-131300D</pre>
<pre class="execute-body-output">            timestamp start/stop: 2025-04-21 13:13:00+00 / 2025-04-21 13:13:01+00
            wal start/stop: 000000010000000000000004 / 000000010000000000000005
            database size: 23.2MB, database backup size: 9.1KB
            repo1: backup set size: 2.9MB, backup size: 832B
            backup reference total: 1 full</pre>
</div></div><div class="section-body-text">
The <span class="cmd">info</span> command operates on a single stanza or all stanzas. Text output is the default and gives a human-readable summary of backups for the stanza(s) requested. This format is subject to change with any release.<br/>
<br/>
For machine-readable output use <span class="br-option">--output=json</span>. The JSON output contains far more information than the text output and is kept stable unless a bug is found.<br/>
<br/>
Each stanza has a separate section and it is possible to limit output to a single stanza with the <span class="br-option">--stanza</span> option. The stanza '<span class="id">status</span>' gives a brief indication of the stanza's health. If this is '<span class="id">ok</span>' then <span class="backrest">pgBackRest</span> is functioning normally. If there are multiple repositories, then a status of '<span class="id">mixed</span>' indicates that the stanza is not in a healthy state on one or more of the repositories; in this case the state of the stanza will be detailed per repository. For cases in which an error on a repository occurred that is not one of the known error codes, then an error code of '<span class="id">other</span>' will be used and the full error details will be provided. The '<span class="id">wal archive min/max</span>' shows the minimum and maximum WAL currently stored in the archive and, in the case of multiple repositories, will be reported across all repositories unless the <span class="br-option">--repo</span> option is set. Note that there may be gaps due to archive retention policies or other reasons.<br/>
<br/>
The '<span class="id">backup/expire running</span>' message will appear beside the '<span class="id">status</span>' information if one of those commands is currently running on the host.<br/>
<br/>
The backups are displayed oldest to newest. The oldest backup will <i>always</i> be a full backup (indicated by an <span class="id">F</span> at the end of the label) but the newest backup can be full, differential (ends with <span class="id">D</span>), or incremental (ends with <span class="id">I</span>).<br/>
<br/>
The '<span class="id">timestamp start/stop</span>' defines the time period when the backup ran. The '<span class="id">timestamp stop</span>' can be used to determine the backup to use when performing Point-In-Time Recovery. More information about Point-In-Time Recovery can be found in the <a href="#pitr">Point-In-Time Recovery</a> section.<br/>
<br/>
The '<span class="id">wal start/stop</span>' defines the WAL range that is required to make the database consistent when restoring. The <span class="cmd">backup</span> command will ensure that this WAL range is in the archive before completing.<br/>
<br/>
The '<span class="id">database size</span>' is the full uncompressed size of the database while '<span class="id">database backup size</span>' is the amount of data in the database to actually back up (these will be the same for full backups).<br/>
<br/>
The '<span class="id">repo</span>' indicates in which repository this backup resides. The '<span class="id">backup set size</span>' includes all the files from this backup and any referenced backups in the repository that are required to restore the database from this backup while '<span class="id">backup size</span>' includes only the files in this backup (these will also be the same for full backups). Repository sizes reflect compressed file sizes if compression is enabled in <span class="backrest">pgBackRest</span>.<br/>
<br/>
The '<span class="id">backup reference total</span>' summarizes the list of additional backups that are required to restore this backup. Use the <span class="br-option">--set</span> option to display the complete reference list.
</div></div></div><div class="section2"><a id="quickstart/perform-restore"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Restore a Backup
</div></div><div class="section-body"><div class="section-body-text">
Backups can protect you from a number of disaster scenarios, the most common of which are hardware failure and data corruption. The easiest way to simulate data corruption is to remove an important <span class="postgres">PostgreSQL</span> cluster file.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Stop the demo cluster and delete the <span class="file">pg_control</span> file
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl stop postgresql-13.service</pre>
<pre class="execute-body-cmd">sudo -u postgres rm /var/lib/pgsql/13/data/global/pg_control</pre>
</div></div><div class="section-body-text">
Starting the cluster without this important file will result in an error.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Attempt to start the corrupted demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl start postgresql-13.service</pre>
<pre class="execute-body-cmd">sudo systemctl status postgresql-13.service</pre>
<pre class="execute-body-output">postgresql-13.service - PostgreSQL 13 database server
    Loaded: loaded (/usr/lib/systemd/system/postgresql-13.service, disabled)</pre>
<pre class="execute-body-output-highlight-error">    Active: failed (failed)</pre>
</div></div><div class="section-body-text">
To restore a backup of the <span class="postgres">PostgreSQL</span> cluster run <span class="backrest">pgBackRest</span> with the <span class="cmd">restore</span> command. The cluster needs to be stopped (in this case it is already stopped) and all files must be removed from the <span class="postgres">PostgreSQL</span> data directory.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Remove old files from demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres find /var/lib/pgsql/13/data -mindepth 1 -delete</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Restore the demo cluster and start <span class="postgres">PostgreSQL</span>
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo restore</pre>
<pre class="execute-body-cmd">sudo systemctl start postgresql-13.service</pre>
</div></div><div class="section-body-text">
This time the cluster started successfully since the restore replaced the missing <span class="file">pg_control</span> file.
</div><div class="section-body-text">
More information about the <span class="cmd">restore</span> command can be found in the <a href="#restore">Restore</a> section.
</div></div></div></div></div><div class="section1"><a id="monitor"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Monitoring
</div></div><div class="section-body"><div class="section-body-text">
Monitoring is an important part of any production system. There are many tools available and <span class="backrest">pgBackRest</span> can be monitored on any of them with a little work.
</div><div class="section-body-text">
<span class="backrest">pgBackRest</span> can output information about the repository in JSON format which includes a list of all backups for each stanza and WAL archive info.
</div><div class="section2"><a id="monitor/postgresql"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
In <span class="postgres">PostgreSQL</span>
</div></div><div class="section-body"><div class="section-body-text">
The <span class="postgres">PostgreSQL</span> <span class="id">COPY</span> command allows <span class="backrest">pgBackRest</span> info to be loaded into a table. The following example wraps that logic in a function that can be used to perform real-time queries.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Load <span class="backrest">pgBackRest</span> info function for <span class="postgres">PostgreSQL</span>
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres cat \
       /var/lib/pgsql/pgbackrest/doc/example/pgsql-pgbackrest-info.sql</pre>
<pre class="execute-body-output">-- An example of monitoring pgBackRest from within PostgreSQL
--
-- Use copy to export data from the pgBackRest info command into the jsonb
-- type so it can be queried directly by PostgreSQL.

-- Create monitor schema
create schema monitor;

-- Get pgBackRest info in JSON format
create function monitor.pgbackrest_info()
    returns jsonb AS $$
declare
    data jsonb;
begin
    -- Create a temp table to hold the JSON data
    create temp table temp_pgbackrest_data (data text);

    -- Copy data into the table directly from the pgBackRest info command
    copy temp_pgbackrest_data (data)
        from program
            'pgbackrest --output=json info' (format text);

    select replace(temp_pgbackrest_data.data, E'\n', '\n')::jsonb
      into data
      from temp_pgbackrest_data;

    drop table temp_pgbackrest_data;

    return data;
end $$ language plpgsql;</pre>
<pre class="execute-body-cmd">sudo -u postgres psql -f \
       /var/lib/pgsql/pgbackrest/doc/example/pgsql-pgbackrest-info.sql</pre>
</div></div><div class="section-body-text">
Now the <span class="id">monitor.pgbackrest_info()</span> function can be used to determine the last successful backup time and archived WAL for a stanza.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Query last successful backup time and archived WAL
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres cat \
       /var/lib/pgsql/pgbackrest/doc/example/pgsql-pgbackrest-query.sql</pre>
<pre class="execute-body-output">-- Get last successful backup for each stanza
--
-- Requires the monitor.pgbackrest_info function.
with stanza as
(
    select data->'name' as name,
           data->'backup'->(
               jsonb_array_length(data->'backup') - 1) as last_backup,
           data->'archive'->(
               jsonb_array_length(data->'archive') - 1) as current_archive
      from jsonb_array_elements(monitor.pgbackrest_info()) as data
)
select name,
       to_timestamp(
           (last_backup->'timestamp'->>'stop')::numeric) as last_successful_backup,
       current_archive->>'max' as last_archived_wal
  from stanza;</pre>
<pre class="execute-body-cmd">sudo -u postgres psql -f \
       /var/lib/pgsql/pgbackrest/doc/example/pgsql-pgbackrest-query.sql</pre>
<pre class="execute-body-output">  name  | last_successful_backup |    last_archived_wal     
--------+------------------------+--------------------------
 "demo" | 2025-04-21 13:13:01+00 | 000000010000000000000005
(1 row)</pre>
</div></div></div></div></div></div><div class="section1"><a id="backup"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Backup
</div></div><div class="section-body"><div class="section-body-text">
When multiple repositories are configured, <span class="backrest">pgBackRest</span> will backup to the highest priority repository (e.g. <span class="id">repo1</span>) unless the <span class="br-option">--repo</span> option is specified.<br/>
<br/>
<span class="backrest">pgBackRest</span> does not have a built-in scheduler so it's best to run it from cron or some other scheduling mechanism.<br/>
<br/>
See <a href="#quickstart/perform-backup">Perform a Backup</a> for more details and examples.
</div><div class="section2"><a id="backup/bundle"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
File Bundling
</div></div><div class="section-body"><div class="section-body-text">
Bundling files together in the repository saves time during the backup and some space in the repository. This is especially pronounced when the repository is stored on an object store such as <span class="host">S3</span>. Per-file creation time on object stores is higher and very small files might cost as much to store as larger files.
</div><div class="section-body-text">
The file bundling feature is enabled with the <span class="br-option">repo-bundle</span> option.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="br-option">repo1-bundle</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-bundle=y<br/>
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO<br/>
repo1-cipher-type=aes-256-cbc<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-full=2<br/>
start-fast=y<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div><div class="section-body-text">
A full backup without file bundling will have 1000+ files in the backup path, but with bundling the total number of files is greatly reduced. An additional benefit is that zero-length files are not stored (except in the manifest), whereas in a normal backup each zero-length file is stored individually.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Perform a full backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --type=full backup</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Check file total
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres find /var/lib/pgbackrest/backup/demo/latest/ -type f | wc -l</pre>
<pre class="execute-body-output">5</pre>
</div></div><div class="section-body-text">
The <span class="br-option">repo-bundle-size</span> and <span class="br-option">repo-bundle-limit</span> options can be used for tuning, though the defaults should be optimal in most cases.
</div><div class="section-body-text">
While file bundling is generally more efficient, the downside is that it is more difficult to manually retrieve files from the repository. It may not be ideal for deduplicated storage since each full backup will arrange files in the bundles differently. Lastly, file bundles cannot be resumed, so be careful not to set <span class="br-option">repo-bundle-size</span> too high.
</div></div></div><div class="section2"><a id="backup/block"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Block Incremental
</div></div><div class="section-body"><div class="section-body-text">
Block incremental backups save space by only storing the parts of a file that have changed since the prior backup rather than storing the entire file.
</div><div class="section-body-text">
The block incremental feature is enabled with the <span class="br-option">repo-block</span> option and it works best when enabled for all backup types. File bundling must also be enabled.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="br-option">repo1-block</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-block=y<br/>
repo1-bundle=y<br/>
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO<br/>
repo1-cipher-type=aes-256-cbc<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-full=2<br/>
start-fast=y<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div></div></div><div class="section2"><a id="backup/annotate"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Backup Annotations
</div></div><div class="section-body"><div class="section-body-text">
Users can attach informative key/value pairs to the backup. This option may be used multiple times to attach multiple annotations.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Perform a full backup with annotations
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --annotation=source="demo backup" \
       --annotation=key=value --type=full backup</pre>
</div></div><div class="section-body-text">
Annotations are output by the <span class="cmd">info</span> command text output when a backup is specified with <span class="br-option">--set</span> and always appear in the JSON output.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Get info for the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --set=20250421-131317F info</pre>
<pre class="execute-body-output">stanza: demo
    status: ok
    cipher: aes-256-cbc

    db (current)
        wal archive min/max (13): 000000020000000000000007/000000020000000000000009

        full backup: 20250421-131317F
            timestamp start/stop: 2025-04-21 13:13:17+00 / 2025-04-21 13:13:19+00
            wal start/stop: 000000020000000000000008 / 000000020000000000000009
            lsn start/stop: 0/8000028 / 0/9000050
            database size: 23.2MB, database backup size: 23.2MB
            repo1: backup size: 2.9MB
            database list: postgres (13383)</pre>
<pre class="execute-body-output-highlight">            annotation(s)</pre>
<pre class="execute-body-output">                key: value
                source: demo backup</pre>
</div></div><div class="section-body-text">
Annotations included with the <span class="cmd">backup</span> command can be added, modified, or removed afterwards using the <span class="cmd">annotate</span> command.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Change backup annotations
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --set=20250421-131317F \
       --annotation=key= --annotation=new_key=new_value annotate</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --set=20250421-131317F info</pre>
<pre class="execute-body-output">stanza: demo
    status: ok
    cipher: aes-256-cbc

    db (current)
        wal archive min/max (13): 000000020000000000000007/000000020000000000000009

        full backup: 20250421-131317F
            timestamp start/stop: 2025-04-21 13:13:17+00 / 2025-04-21 13:13:19+00
            wal start/stop: 000000020000000000000008 / 000000020000000000000009
            lsn start/stop: 0/8000028 / 0/9000050
            database size: 23.2MB, database backup size: 23.2MB
            repo1: backup size: 2.9MB
            database list: postgres (13383)</pre>
<pre class="execute-body-output-highlight">            annotation(s)</pre>
<pre class="execute-body-output">                new_key: new_value
                source: demo backup</pre>
</div></div></div></div></div></div><div class="section1"><a id="retention"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Retention
</div></div><div class="section-body"><div class="section-body-text">
Generally it is best to retain as many backups as possible to provide a greater window for <a href="#pitr">Point-in-Time Recovery</a>, but practical concerns such as disk space must also be considered. Retention options remove older backups once they are no longer needed.
</div><div class="section-body-text">
<span class="backrest">pgBackRest</span> does full backup rotation based on the retention type which can be a count or a time period. When a count is specified, then expiration is not concerned with when the backups were created but with how many must be retained. Differential backups are count-based but will always be expired when the full backup they depend on is expired. Incremental backups are not expired by retention independently &mdash; they are always expired with their related full or differential backup. See sections <a href="#retention/full">Full Backup Retention</a> and <a href="#retention/diff">Differential Backup Retention</a> for details and examples.<br/>
<br/>
Archived WAL is retained by default for backups that have not expired, however, although not recommended, this schedule can be modified per repository with the retention-archive options. See section <a href="#retention/archive">Archive Retention</a> for details and examples.<br/>
<br/>
The <span class="cmd">expire</span> command is run automatically after each successful backup and can also be run by the user. When run by the user, expiration will occur as defined by the retention settings for each configured repository. If the <span class="br-option">--repo</span> option is provided, expiration will occur only on the specified repository. Expiration can also be limited by the user to a specific backup set with the <span class="br-option">--set</span> option and, unless the <span class="br-option">--repo</span> option is specified, all repositories will be searched and any matching the set criteria will be expired. It should be noted that the archive retention schedule will be checked and performed any time the <span class="cmd">expire</span> command is run.
</div><div class="section2"><a id="retention/full"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Full Backup Retention
</div></div><div class="section-body"><div class="section-body-text">
The <span class="br-option">repo1-retention-full-type</span> determines how the option <span class="br-option">repo1-retention-full</span> is interpreted; either as the count of full backups to be retained or how many days to retain full backups. New backups must be completed before expiration will occur &mdash; that means if <span class="br-setting">repo1-retention-full-type=count</span> and <span class="br-setting">repo1-retention-full=2</span> then there will be three full backups stored before the oldest one is expired, or if <span class="br-setting">repo1-retention-full-type=time</span> and <span class="br-setting">repo1-retention-full=20</span> then there must be one full backup that is at least 20 days old before expiration can occur.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="br-option">repo1-retention-full</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-block=y<br/>
repo1-bundle=y<br/>
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO<br/>
repo1-cipher-type=aes-256-cbc<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-full=2<br/>
start-fast=y<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div><div class="section-body-text">
Backup <span class="br-setting">repo1-retention-full=2</span> but currently there is only one full backup so the next full backup to run will not expire any full backups.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Perform a full backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --type=full \
       --log-level-console=detail backup</pre>
<pre class="execute-body-output">       [filtered 948 lines of output]
P00   INFO: repo1: remove expired backup 20250421-131313F
P00 DETAIL: repo1: 13-1 archive retention on backup 20250421-131317F, start = 000000020000000000000008</pre>
<pre class="execute-body-output-highlight">P00   INFO: repo1: 13-1 remove archive, start = 000000020000000000000007, stop = 000000020000000000000007</pre>
<pre class="execute-body-output">P00   INFO: expire command end: completed successfully</pre>
</div></div><div class="section-body-text">
Archive <i>is</i> expired because WAL segments were generated before the oldest backup. These are not useful for recovery &mdash; only WAL segments generated after a backup can be used to recover that backup.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Perform a full backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --type=full \
       --log-level-console=info backup</pre>
<pre class="execute-body-output">       [filtered 11 lines of output]
P00   INFO: repo1: expire full backup 20250421-131317F
P00   INFO: repo1: remove expired backup 20250421-131317F</pre>
<pre class="execute-body-output-highlight">P00   INFO: repo1: 13-1 remove archive, start = 000000020000000000000008, stop = 000000020000000000000009</pre>
<pre class="execute-body-output">P00   INFO: expire command end: completed successfully</pre>
</div></div><div class="section-body-text">
The <span class="id">20250421-131256F</span> full backup is expired and archive retention is based on the <span class="id">20250421-131321F</span> which is now the oldest full backup.
</div></div></div><div class="section2"><a id="retention/diff"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Differential Backup Retention
</div></div><div class="section-body"><div class="section-body-text">
Set <span class="br-option">repo1-retention-diff</span> to the number of differential backups required. Differentials only rely on the prior full backup so it is possible to create a <q>rolling</q> set of differentials for the last day or more. This allows quick restores to recent points-in-time but reduces overall space consumption.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="br-option">repo1-retention-diff</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-block=y<br/>
repo1-bundle=y<br/>
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO<br/>
repo1-cipher-type=aes-256-cbc<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-diff=1<br/>
repo1-retention-full=2<br/>
start-fast=y<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div><div class="section-body-text">
Backup <span class="br-setting">repo1-retention-diff=1</span> so two differentials will need to be performed before one is expired. An incremental backup is added to demonstrate incremental expiration, which in this case depends on the differential expiration.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Perform differential and incremental backups
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --type=diff backup</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --type=incr backup</pre>
</div></div><div class="section-body-text">
Now performing a differential backup will expire the previous differential and incremental backups leaving only one differential backup.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Perform a differential backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --type=diff \
       --log-level-console=info backup</pre>
<pre class="execute-body-output">       [filtered 10 lines of output]
P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.55.0: --exec-id=2288-640159d6 --log-level-console=info --no-log-timestamp --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-diff=1 --repo1-retention-full=2 --stanza=demo</pre>
<pre class="execute-body-output-highlight">P00   INFO: repo1: expire diff backup set 20250421-131323F_20250421-131326D, 20250421-131323F_20250421-131328I</pre>
<pre class="execute-body-output">P00   INFO: repo1: remove expired backup 20250421-131323F_20250421-131328I
P00   INFO: repo1: remove expired backup 20250421-131323F_20250421-131326D
P00   INFO: expire command end: completed successfully</pre>
</div></div></div></div><div class="section2"><a id="retention/archive"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Archive Retention
</div></div><div class="section-body"><div class="section-body-text">
Although <span class="backrest">pgBackRest</span> automatically removes archived WAL segments when expiring backups (the default expires WAL for full backups based on the <span class="br-option">repo1-retention-full</span> option), it may be useful to expire archive more aggressively to save disk space. Note that full backups are treated as differential backups for the purpose of differential archive retention.
</div><div class="section-body-text">
Expiring archive will never remove WAL segments that are required to make a backup consistent. However, since Point-in-Time-Recovery (PITR) only works on a continuous WAL stream, care should be taken when aggressively expiring archive outside of the normal backup expiration process. To determine what will be expired without actually expiring anything, the <span class="br-option">dry-run</span> option can be provided on the command line with the <span class="cmd">expire</span> command.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="br-option">repo1-retention-diff</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-block=y<br/>
repo1-bundle=y<br/>
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO<br/>
repo1-cipher-type=aes-256-cbc<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-diff=2<br/>
repo1-retention-full=2<br/>
start-fast=y<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Perform differential backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --type=diff \
       --log-level-console=info backup</pre>
<pre class="execute-body-output">       [filtered 6 lines of output]
P00   INFO: backup stop archive = 000000020000000000000017, lsn = 0/17000050
P00   INFO: check archive for segment(s) 000000020000000000000016:000000020000000000000017</pre>
<pre class="execute-body-output-highlight">P00   INFO: new backup label = 20250421-131323F_20250421-131332D</pre>
<pre class="execute-body-output">P00   INFO: diff backup size = 11.4KB, file total = 936
P00   INFO: backup command end: completed successfully
       [filtered 2 lines of output]</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Expire archive
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --log-level-console=detail \
       --repo1-retention-archive-type=diff --repo1-retention-archive=1 expire</pre>
<pre class="execute-body-output">P00   INFO: expire command begin 2.55.0: --exec-id=2478-d1622894 --log-level-console=detail --no-log-timestamp --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo1-retention-archive=1 --repo1-retention-archive-type=diff --repo1-retention-diff=2 --repo1-retention-full=2 --stanza=demo
P00 DETAIL: repo1: 13-1 archive retention on backup 20250421-131321F, start = 00000002000000000000000A, stop = 00000002000000000000000B
P00 DETAIL: repo1: 13-1 archive retention on backup 20250421-131323F, start = 00000002000000000000000D, stop = 00000002000000000000000D</pre>
<pre class="execute-body-output-highlight">P00 DETAIL: repo1: 13-1 archive retention on backup 20250421-131323F_20250421-131330D, start = 000000020000000000000012, stop = 000000020000000000000013</pre>
<pre class="execute-body-output">P00 DETAIL: repo1: 13-1 archive retention on backup 20250421-131323F_20250421-131332D, start = 000000020000000000000016</pre>
<pre class="execute-body-output-highlight">P00   INFO: repo1: 13-1 remove archive, start = 00000002000000000000000C, stop = 00000002000000000000000C
P00   INFO: repo1: 13-1 remove archive, start = 00000002000000000000000E, stop = 000000020000000000000011
P00   INFO: repo1: 13-1 remove archive, start = 000000020000000000000014, stop = 000000020000000000000015</pre>
<pre class="execute-body-output">P00   INFO: expire command end: completed successfully</pre>
</div></div><div class="section-body-text">
The <span class="id">20250421-131323F_20250421-131330D</span> differential backup has archived WAL segments that must be retained to make the older backups consistent even though they cannot be played any further forward with PITR. WAL segments generated after <span class="id">20250421-131323F_20250421-131330D</span> but before <span class="id">20250421-131323F_20250421-131332D</span> are removed. WAL segments generated after the new backup <span class="id">20250421-131323F_20250421-131332D</span> remain and can be used for PITR.
</div><div class="section-body-text">
Since full backups are considered differential backups for the purpose of differential archive retention, if a full backup is now performed with the same settings, only the archive for that full backup is retained for PITR.
</div></div></div></div></div><div class="section1"><a id="restore"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Restore
</div></div><div class="section-body"><div class="section-body-text">
The restore command automatically defaults to selecting the latest backup from the first repository where backups exist (see <a href="#quickstart/perform-restore">Quick Start - Restore a Backup</a>). The order in which the repositories are checked is dictated by the <span class="file">pgbackrest.conf</span> (e.g. repo1 will be checked before repo2). To select from a specific repository, the <span class="br-option">--repo</span> option can be passed (e.g. <span class="br-option">--repo=1</span>). The <span class="br-option">--set</span> option can be passed if a backup other than the latest is desired.<br/>
<br/>
When PITR of <span class="br-option">--type=time</span> or <span class="br-option">--type=lsn</span> is specified, then the target time or target lsn must be specified with the <span class="br-option">--target</span> option. If a backup is not specified via the <span class="br-option">--set</span> option, then the configured repositories will be checked, in order, for a backup that contains the requested time or lsn. If no matching backup is found, the latest backup from the first repository containing backups will be used for <span class="br-option">--type=time</span> while no backup will be selected for <span class="br-option">--type=lsn</span>. For other types of PITR, e.g. <span class="id">xid</span>, the <span class="br-option">--set</span> option must be provided if the target is prior to the latest backup. See <a href="#pitr">Point-in-Time Recovery</a> for more details and examples.<br/>
<br/>
Replication slots are not included per recommendation of <span class="postgres">PostgreSQL</span>. See <a href="https://www.postgresql.org/docs/current/continuous-archiving.html#BACKUP-LOWLEVEL-BASE-BACKUP-DATA">Backing Up The Data Directory</a> in the <span class="postgres">PostgreSQL</span> documentation for more information.
</div><div class="section-body-text">
The following sections introduce additional <span class="cmd">restore</span> command features.
</div><div class="section2"><a id="restore/ownership"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
File Ownership
</div></div><div class="section-body"><div class="section-body-text">
If a <span class="cmd">restore</span> is run as a non-root user (the typical scenario) then all files restored will belong to the user/group executing <span class="backrest">pgBackRest</span>. If existing files are not owned by the executing user/group then an error will result if the ownership cannot be updated to the executing user/group. In that case the file ownership will need to be updated by a privileged user before the restore can be retried.
</div><div class="section-body-text">
If a <span class="cmd">restore</span> is run as the <span class="id">root</span> user then <span class="backrest">pgBackRest</span> will attempt to recreate the ownership recorded in the manifest when the backup was made. Only user/group <b>names</b> are stored in the manifest so the same names must exist on the restore host for this to work. If the user/group name cannot be found locally then the user/group of the <span class="postgres">PostgreSQL</span> data directory will be used and finally <span class="id">root</span> if the data directory user/group cannot be mapped to a name.
</div></div></div><div class="section2"><a id="restore/option-delta"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Delta Option
</div></div><div class="section-body"><div class="section-body-text">
<a href="#quickstart/perform-restore">Restore a Backup</a> in <a href="#quickstart">Quick Start</a> required the database cluster directory to be cleaned before the <span class="cmd">restore</span> could be performed. The <span class="br-option">delta</span> option allows <span class="backrest">pgBackRest</span> to automatically determine which files in the database cluster directory can be preserved and which ones need to be restored from the backup &mdash; it also <i>removes</i> files not present in the backup manifest so it will dispose of divergent changes. This is accomplished by calculating a <a href="https://en.wikipedia.org/wiki/SHA-1">SHA-1</a> cryptographic hash for each file in the database cluster directory. If the <span class="id">SHA-1</span> hash does not match the hash stored in the backup then that file will be restored. This operation is very efficient when combined with the <span class="br-option">process-max</span> option. Since the <span class="postgres">PostgreSQL</span> server is shut down during the restore, a larger number of processes can be used than might be desirable during a backup when the <span class="postgres">PostgreSQL</span> server is running.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Stop the demo cluster, perform delta restore
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl stop postgresql-13.service</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --delta \
       --log-level-console=detail restore</pre>
<pre class="execute-body-output">       [filtered 2 lines of output]
P00 DETAIL: check '/var/lib/pgsql/13/data' exists
P00 DETAIL: remove 'global/pg_control' so cluster will not start if restore does not complete</pre>
<pre class="execute-body-output-highlight">P00   INFO: remove invalid files/links/paths from '/var/lib/pgsql/13/data'</pre>
<pre class="execute-body-output">P00 DETAIL: remove invalid file '/var/lib/pgsql/13/data/backup_label.old'
P00 DETAIL: remove invalid file '/var/lib/pgsql/13/data/base/13383/pg_internal.init'
       [filtered 981 lines of output]</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Restart <span class="postgres">PostgreSQL</span>
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl start postgresql-13.service</pre>
</div></div></div></div><div class="section2"><a id="restore/option-db-include"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Restore Selected Databases
</div></div><div class="section-body"><div class="section-body-text">
There may be cases where it is desirable to selectively restore specific databases from a cluster backup. This could be done for performance reasons or to move selected databases to a machine that does not have enough space to restore the entire cluster backup.
</div><div class="section-body-text">
To demonstrate this feature two databases are created: test1 and test2.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create two test databases
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c "create database test1;"</pre>
<pre class="execute-body-output">CREATE DATABASE</pre>
<pre class="execute-body-cmd">sudo -u postgres psql -c "create database test2;"</pre>
<pre class="execute-body-output">CREATE DATABASE</pre>
</div></div><div class="section-body-text">
Each test database will be seeded with tables and data to demonstrate that recovery works with selective restore.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create a test table in each database
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c "create table test1_table (id int); \
       insert into test1_table (id) values (1);" test1</pre>
<pre class="execute-body-output">INSERT 0 1</pre>
<pre class="execute-body-cmd">sudo -u postgres psql -c "create table test2_table (id int); \
       insert into test2_table (id) values (2);" test2</pre>
<pre class="execute-body-output">INSERT 0 1</pre>
</div></div><div class="section-body-text">
A fresh backup is run so <span class="backrest">pgBackRest</span> is aware of the new databases.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Perform a backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --type=incr backup</pre>
</div></div><div class="section-body-text">
One of the main reasons to use selective restore is to save space. The size of the test1 database is shown here so it can be compared with the disk utilization after a selective restore.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Show space used by test1 database
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres du -sh /var/lib/pgsql/13/data/base/32768</pre>
<pre class="execute-body-output">7.8M	/var/lib/pgsql/13/data/base/32768</pre>
</div></div><div class="section-body-text">
If the database to restore is not known, use the <span class="cmd">info</span> command <span class="br-option">set</span> option to discover databases that are part of the backup set.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Show database list for backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo \
       --set=20250421-131323F_20250421-131343I info</pre>
<pre class="execute-body-output">       [filtered 12 lines of output]
            repo1: backup size: 1.9MB
            backup reference list: 20250421-131323F, 20250421-131323F_20250421-131332D</pre>
<pre class="execute-body-output-highlight">            database list: postgres (13383), test1 (32768), test2 (32769)</pre>
</div></div><div class="section-body-text">
Stop the cluster and restore only the test2 database. Built-in databases (<span class="id">template0</span>, <span class="id">template1</span>, and <span class="id">postgres</span>) are always restored.
</div><div class="admonition"><div class="warning">
WARNING:
</div><div class="warning-text">
Recovery may error unless <span class="br-option">--type=immediate</span> is specified. This is because after consistency is reached <span class="postgres">PostgreSQL</span> will flag zeroed pages as errors even for a full-page write. For <span class="postgres">PostgreSQL</span> &ge; <span class="host">13</span> the <span class="pg-option">ignore_invalid_pages</span> setting may be used to ignore invalid pages. In this case it is important to check the logs after recovery to ensure that no invalid pages were reported in the selected databases.
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Restore from last backup including only the test2 database
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl stop postgresql-13.service</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --delta \
       --db-include=test2 --type=immediate --target-action=promote restore</pre>
<pre class="execute-body-cmd">sudo systemctl start postgresql-13.service</pre>
</div></div><div class="section-body-text">
Once recovery is complete the test2 database will contain all previously created tables and data.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Demonstrate that the test2 database was recovered
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c "select * from test2_table;" test2</pre>
<pre class="execute-body-output"> id 
----
  2
(1 row)</pre>
</div></div><div class="section-body-text">
The test1 database, despite successful recovery, is not accessible. This is because the entire database was restored as sparse, zeroed files. <span class="postgres">PostgreSQL</span> can successfully apply WAL on the zeroed files but the database as a whole will not be valid because key files contain no data. This is purposeful to prevent the database from being accidentally used when it might contain partial data that was applied during WAL replay.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Attempting to connect to the test1 database will produce an error
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c "select * from test1_table;" test1</pre>
<pre class="execute-body-output-highlight-error">psql: error: connection to server on socket "/run/postgresql/.s.PGSQL.5432" failed: FATAL:  relation mapping file "base/32768/pg_filenode.map" contains invalid data</pre>
</div></div><div class="section-body-text">
Since the test1 database is restored with sparse, zeroed files it will only require as much space as the amount of WAL that is written during recovery. While the amount of WAL generated during a backup and applied during recovery can be significant it will generally be a small fraction of the total database size, especially for large databases where this feature is most likely to be useful.
</div><div class="section-body-text">
It is clear that the test1 database uses far less disk space during the selective restore than it would have if the entire database had been restored.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Show space used by test1 database after recovery
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres du -sh /var/lib/pgsql/13/data/base/32768</pre>
<pre class="execute-body-output">8.0K	/var/lib/pgsql/13/data/base/32768</pre>
</div></div><div class="section-body-text">
At this point the only action that can be taken on the invalid test1 database is <span class="id">drop database</span>. <span class="backrest">pgBackRest</span> does not automatically drop the database since this cannot be done until recovery is complete and the cluster is accessible.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Drop the test1 database
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c "drop database test1;"</pre>
<pre class="execute-body-output">DROP DATABASE</pre>
</div></div><div class="section-body-text">
Now that the invalid test1 database has been dropped only the test2 and built-in databases remain.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> List remaining databases
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c "select oid, datname from pg_database order by oid;"</pre>
<pre class="execute-body-output">  oid  |  datname  
-------+-----------
     1 | template1
 13382 | template0
 13383 | postgres</pre>
<pre class="execute-body-output-highlight"> 32769 | test2</pre>
<pre class="execute-body-output">(4 rows)</pre>
</div></div></div></div></div></div><div class="section1"><a id="pitr"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Point-in-Time Recovery
</div></div><div class="section-body"><div class="section-body-text">
<a href="#quickstart/perform-restore">Restore a Backup</a> in <a href="#quickstart">Quick Start</a> performed default recovery, which is to play all the way to the end of the WAL stream. In the case of a hardware failure this is usually the best choice but for data corruption scenarios (whether machine or human in origin) Point-in-Time Recovery (PITR) is often more appropriate.
</div><div class="section-body-text">
Point-in-Time Recovery (PITR) allows the WAL to be played from a backup to a specified lsn, time, transaction id, or recovery point. For common recovery scenarios time-based recovery is arguably the most useful. A typical recovery scenario is to restore a table that was accidentally dropped or data that was accidentally deleted. Recovering a dropped table is more dramatic so that's the example given here but deleted data would be recovered in exactly the same way.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create a table with very important data
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c "begin; \
       create table important_table (message text); \
       insert into important_table values ('Important Data'); \
       commit; \
       select * from important_table;"</pre>
<pre class="execute-body-output">    message     
----------------</pre>
<pre class="execute-body-output-highlight"> Important Data</pre>
<pre class="execute-body-output">(1 row)</pre>
</div></div><div class="section-body-text">
It is important to represent the time as reckoned by <span class="postgres">PostgreSQL</span> and to include timezone offsets. This reduces the possibility of unintended timezone conversions and an unexpected recovery result.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Get the time from <span class="postgres">PostgreSQL</span>
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -Atc "select current_timestamp"</pre>
<pre class="execute-body-output">2025-04-21 13:13:56.887384+00</pre>
</div></div><div class="section-body-text">
Now that the time has been recorded the table is dropped. In practice finding the exact time that the table was dropped is a lot harder than in this example. It may not be possible to find the exact time, but some forensic work should be able to get you close.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Drop the important table
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c "begin; \
       drop table important_table; \
       commit; \
       select * from important_table;"</pre>
<pre class="execute-body-output-highlight-error">ERROR:  relation "important_table" does not exist</pre>
<pre class="execute-body-output">LINE 1: ...le important_table;     commit;     select * from important_...
                                                             ^</pre>
</div></div><div class="section-body-text">
If the wrong backup is selected for restore then recovery to the required time target will fail. To demonstrate this a new incremental backup is performed where <span class="id">important_table</span> does not exist.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Perform an incremental backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --type=incr backup</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest info</pre>
<pre class="execute-body-output">       [filtered 38 lines of output]
            backup reference total: 1 full, 1 diff
</pre>
<pre class="execute-body-output-highlight">        incr backup: 20250421-131323F_20250421-131358I</pre>
<pre class="execute-body-output">            timestamp start/stop: 2025-04-21 13:13:58+00 / 2025-04-21 13:13:59+00
            wal start/stop: 00000004000000000000001A / 00000004000000000000001A
       [filtered 2 lines of output]</pre>
</div></div><div class="section-body-text">
It will not be possible to recover the lost table from this backup since <span class="postgres">PostgreSQL</span> can only play forward, not backward.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Attempt recovery from an incorrect backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl stop postgresql-13.service</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --delta \
       --set=20250421-131323F_20250421-131358I --target-timeline=current \
       --type=time "--target=2025-04-21 13:13:56.887384+00" --target-action=promote restore</pre>
<pre class="execute-body-cmd">sudo systemctl start postgresql-13.service</pre>
<pre class="execute-body-cmd">sudo -u postgres cat /var/lib/pgsql/13/data/log/postgresql.log</pre>
<pre class="execute-body-output">       [filtered 11 lines of output]
LOG:  database system is ready to accept read only connections
LOG:  redo done at 0/1A000100</pre>
<pre class="execute-body-output-highlight">FATAL:  recovery ended before configured recovery target was reached</pre>
<pre class="execute-body-output">LOG:  startup process (PID 3443) exited with exit code 1
LOG:  terminating any other active server processes</pre>
</div></div><div class="section-body-text">
A reliable method is to allow <span class="backrest">pgBackRest</span> to automatically select a backup capable of recovery to the time target, i.e. a backup that ended before the specified time.
</div><div class="admonition"><div class="note">
NOTE:
</div><div class="note-text">
<span class="backrest">pgBackRest</span> cannot automatically select a backup when the restore type is <span class="id">xid</span> or <span class="id">name</span>.
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Restore the demo cluster to <span class="id">2025-04-21 13:13:56.887384+00</span>
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --delta \
       --type=time "--target=2025-04-21 13:13:56.887384+00" \
       --target-action=promote restore</pre>
<pre class="execute-body-cmd">sudo -u postgres cat /var/lib/pgsql/13/data/postgresql.auto.conf</pre>
<pre class="execute-body-output">       [filtered 9 lines of output]
# Recovery settings generated by pgBackRest restore on 2025-04-21 13:14:05
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'</pre>
<pre class="execute-body-output-highlight">recovery_target_time = '2025-04-21 13:13:56.887384+00'</pre>
<pre class="execute-body-output">recovery_target_action = 'promote'</pre>
</div></div><div class="section-body-text">
<span class="backrest">pgBackRest</span> has generated the recovery settings in <span class="file">postgresql.auto.conf</span> so <span class="postgres">PostgreSQL</span> can be started immediately. <span class="id">%f</span> is how <span class="postgres">PostgreSQL</span> specifies the WAL segment it needs and <span class="id">%p</span> is the location where it should be copied. Once <span class="postgres">PostgreSQL</span> has finished recovery the table will exist again and can be queried.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Start <span class="postgres">PostgreSQL</span> and check that the important table exists
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl start postgresql-13.service</pre>
<pre class="execute-body-cmd">sudo -u postgres psql -c "select * from important_table"</pre>
<pre class="execute-body-output">    message     
----------------</pre>
<pre class="execute-body-output-highlight"> Important Data</pre>
<pre class="execute-body-output">(1 row)</pre>
</div></div><div class="section-body-text">
The <span class="postgres">PostgreSQL</span> log also contains valuable information. It will indicate the time and transaction where the recovery stopped and also give the time of the last transaction to be applied.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Examine the <span class="postgres">PostgreSQL</span> log output
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres cat /var/lib/pgsql/13/data/log/postgresql.log</pre>
<pre class="execute-body-output">       [filtered 5 lines of output]
LOG:  database system was interrupted; last known up at 2025-04-21 13:13:43 UTC
LOG:  restored log file "00000004.history" from archive</pre>
<pre class="execute-body-output-highlight">LOG:  starting point-in-time recovery to 2025-04-21 13:13:56.887384+00</pre>
<pre class="execute-body-output">LOG:  restored log file "00000004.history" from archive
LOG:  restored log file "000000040000000000000019" from archive
       [filtered 2 lines of output]
LOG:  consistent recovery state reached at 0/19000100
LOG:  database system is ready to accept read only connections</pre>
<pre class="execute-body-output-highlight">LOG:  recovery stopping before commit of transaction 495, time 2025-04-21 13:13:58.415355+00</pre>
<pre class="execute-body-output">LOG:  redo done at 0/1901E348</pre>
<pre class="execute-body-output-highlight">LOG:  last completed transaction was at log time 2025-04-21 13:13:55.599557+00</pre>
<pre class="execute-body-output">LOG:  selected new timeline ID: 5
LOG:  archive recovery complete
LOG:  database system is ready to accept connections</pre>
</div></div></div></div><div class="section1"><a id="delete-stanza"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Delete a Stanza
</div></div><div class="section-body"><div class="section-body-text">
The <span class="cmd">stanza-delete</span> command removes data in the repository associated with a stanza.<br/>
<div class="admonition"><div class="warning">WARNING:</div><div class="warning-text">Use this command with caution &mdash; it will permanently remove all backups and archives from the <span class="backrest">pgBackRest</span> repository for the specified stanza.</div></div>To delete a stanza:<br/>
<ul class="list-unordered"><li class="list-unordered">Shut down the <span class="postgres">PostgreSQL</span> cluster associated with the stanza (or use --force to override).</li><li class="list-unordered">Run the <span class="cmd">stop</span> command on the host where the <span class="cmd">stanza-delete</span> command will be run.</li><li class="list-unordered">Run the <span class="cmd">stanza-delete</span> command.</li></ul>Once the command successfully completes, it is the responsibility of the user to remove the stanza from all <span class="backrest">pgBackRest</span> configuration files and/or environment variables.<br/>
<br/>
A stanza may only be deleted from one repository at a time. To delete the stanza from multiple repositories, repeat the <span class="cmd">stanza-delete</span> command for each repository while specifying the <span class="br-option">--repo</span> option.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Stop <span class="postgres">PostgreSQL</span> cluster to be removed
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl stop postgresql-13.service</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Stop <span class="backrest">pgBackRest</span> for the stanza
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stop</pre>
<pre class="execute-body-output">P00   INFO: stop command begin 2.55.0: --exec-id=3734-6522fbe8 --log-level-console=info --no-log-timestamp --stanza=demo</pre>
<pre class="execute-body-output-highlight">P00   INFO: stop command end: completed successfully</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Delete the stanza from one repository
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --repo=1 \
       --log-level-console=info stanza-delete</pre>
<pre class="execute-body-output">P00   INFO: stanza-delete command begin 2.55.0: --exec-id=3760-e53bdbcf --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --repo=1 --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --stanza=demo</pre>
<pre class="execute-body-output-highlight">P00   INFO: stanza-delete command end: completed successfully</pre>
</div></div></div></div><div class="section1"><a id="multi-repo"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Multiple Repositories
</div></div><div class="section-body"><div class="section-body-text">
Multiple repositories may be configured as demonstrated in <a href="#s3-support">S3 Support</a>. A potential benefit is the ability to have a local repository for fast restores and a remote repository for redundancy.
</div><div class="section-body-text">
Some commands, e.g. <span class="cmd">stanza-create</span>/<span class="cmd">stanza-upgrade</span>, will automatically work with all configured repositories while others, e.g. <a href="#delete-stanza">stanza-delete</a>, will require a repository to be specified using the <span class="br-option">repo</span> option. See the <a href="command.html">command reference</a> for details on which commands require the repository to be specified.
</div><div class="section-body-text">
Note that the <span class="br-option">repo</span> option is not required when only <span class="br-option">repo1</span> is configured in order to maintain backward compatibility. However, the <span class="br-option">repo</span> option <i>is</i> required when a single repo is configured as, e.g. <span class="br-option">repo2</span>. This is to prevent command breakage if a new repository is added later.
</div><div class="section-body-text">
The <span class="cmd">archive-push</span> command will always push WAL to the archive in all configured repositories. When a repository cannot be reached, WAL will still be pushed to other repositories. However, for this to work effectively, <span class="br-setting">archive-async=y</span> must be enabled; otherwise, the other repositories can only get one WAL segment ahead of the unreachable repository. Also, note that if WAL cannot be pushed to any repository, then <span class="postgres">PostgreSQL</span> will not remove it from the <span class="path">pg_wal</span> directory, which may cause the volume to run out of space.
</div><div class="section-body-text">
Backups need to be scheduled individually for each repository. In many cases this is desirable since backup types and retention will vary by repository. Likewise, restores must specify a repository. It is generally better to specify a repository for restores that has low latency/cost even if that means more recovery time. Only restore testing can determine which repository will be most efficient.
</div></div></div><div class="section1"><a id="azure-support"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Azure-Compatible Object Store Support
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> supports locating repositories in <span class="host">Azure-compatible</span> object stores. The container used to store the repository must be created in advance &mdash; <span class="backrest">pgBackRest</span> will not do it automatically. The repository can be located in the container root (<span class="path">/</span>) but it's usually best to place it in a subpath so object store logs or other data can also be stored in the container without conflicts.
</div><div class="admonition"><div class="warning">
WARNING:
</div><div class="warning-text">
Do not enable <q>hierarchical namespace</q> as this will cause errors during expire.
</div></div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="host">Azure</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-block=y<br/>
repo1-bundle=y<br/>
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO<br/>
repo1-cipher-type=aes-256-cbc<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-diff=2<br/>
repo1-retention-full=2<br/>
repo2-azure-account=pgbackrest<br/>
repo2-azure-container=demo-container<br/>
repo2-azure-key=YXpLZXk=<br/>
repo2-path=/demo-repo<br/>
repo2-retention-full=4<br/>
repo2-type=azure<br/>
start-fast=y<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div><div class="section-body-text">
Shared access signatures may be used by setting the <span class="br-option">repo2-azure-key-type</span> option to <span class="id">sas</span> and the <span class="br-option">repo2-azure-key</span> option to the shared access signature token.
</div><div class="section-body-text">
Commands are run exactly as if the repository were stored on a local disk.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create the stanza
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stanza-create</pre>
<pre class="execute-body-output">P00   INFO: stanza-create command begin 2.55.0: --exec-id=3926-affd3ca0 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --repo2-azure-account=<redacted> --repo2-azure-container=demo-container --repo2-azure-key=<redacted> --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo2-type=azure --stanza=demo
P00   INFO: stanza-create for stanza 'demo' on repo1
P00   INFO: stanza-create for stanza 'demo' on repo2</pre>
<pre class="execute-body-output-highlight">P00   INFO: stanza-create command end: completed successfully</pre>
</div></div><div class="section-body-text">
File creation time in Azure is relatively slow so <span class="cmd">backup</span>/<span class="cmd">restore</span> performance is improved by enabling <a href="#backup/bundle">file bundling</a>.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Backup the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --repo=2 \
       --log-level-console=info backup</pre>
<pre class="execute-body-output">P00   INFO: backup command begin 2.55.0: --exec-id=3953-68d03872 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --repo=2 --repo2-azure-account=<redacted> --repo2-azure-container=demo-container --repo2-azure-key=<redacted> --repo1-block --repo1-bundle --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo2-type=azure --stanza=demo --start-fast</pre>
<pre class="execute-body-output-highlight">P00   WARN: no prior backup exists, incr backup has been changed to full</pre>
<pre class="execute-body-output">P00   INFO: execute non-exclusive backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 00000005000000000000001B, lsn = 0/1B000028
       [filtered 3 lines of output]
P00   INFO: check archive for segment(s) 00000005000000000000001B:00000005000000000000001B
P00   INFO: new backup label = 20250421-131423F</pre>
<pre class="execute-body-output-highlight">P00   INFO: full backup size = 30.8MB, file total = 1229</pre>
<pre class="execute-body-output">P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.55.0: --exec-id=3953-68d03872 --log-level-console=info --no-log-timestamp --repo=2 --repo2-azure-account=<redacted> --repo2-azure-container=demo-container --repo2-azure-key=<redacted> --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo2-type=azure --stanza=demo</pre>
</div></div></div></div><div class="section1"><a id="s3-support"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
S3-Compatible Object Store Support
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> supports locating repositories in <span class="host">S3-compatible</span> object stores. The bucket used to store the repository must be created in advance &mdash; <span class="backrest">pgBackRest</span> will not do it automatically. The repository can be located in the bucket root (<span class="path">/</span>) but it's usually best to place it in a subpath so object store logs or other data can also be stored in the bucket without conflicts.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="host">S3</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-block=y<br/>
repo1-bundle=y<br/>
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO<br/>
repo1-cipher-type=aes-256-cbc<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-diff=2<br/>
repo1-retention-full=2<br/>
repo2-azure-account=pgbackrest<br/>
repo2-azure-container=demo-container<br/>
repo2-azure-key=YXpLZXk=<br/>
repo2-path=/demo-repo<br/>
repo2-retention-full=4<br/>
repo2-type=azure<br/>
repo3-path=/demo-repo<br/>
repo3-retention-full=4<br/>
repo3-s3-bucket=demo-bucket<br/>
repo3-s3-endpoint=s3.us-east-1.amazonaws.com<br/>
repo3-s3-key=accessKey1<br/>
repo3-s3-key-secret=verySecretKey1<br/>
repo3-s3-region=us-east-1<br/>
repo3-type=s3<br/>
start-fast=y<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div><div class="admonition"><div class="note">
NOTE:
</div><div class="note-text">
The region and endpoint will need to be configured to where the bucket is located. The values given here are for the <span class="id">us-east-1</span> region.
</div></div><div class="section-body-text">
A role should be created to run <span class="backrest">pgBackRest</span> and the bucket permissions should be set as restrictively as possible. If the role is associated with an instance in <span class="host">AWS</span> then <span class="backrest">pgBackRest</span> will automatically retrieve temporary credentials when <span class="br-option">repo3-s3-key-type=auto</span>, which means that keys do not need to be explicitly set in <span class="file">/etc/pgbackrest/pgbackrest.conf</span>.
</div><div class="section-body-text">
This sample <span class="host">Amazon S3</span> policy will restrict all reads and writes to the bucket and repository path.
</div>
<pre class="code-block">{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::demo-bucket"
            ],
            "Condition": {
                "StringEquals": {
                    "s3:prefix": [
                        "",
                        "demo-repo"
                    ],
                    "s3:delimiter": [
                        "/"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::demo-bucket"
            ],
            "Condition": {
                "StringLike": {
                    "s3:prefix": [
                        "demo-repo/*"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:PutObjectTagging",
                "s3:GetObject",
                "s3:GetObjectVersion",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::demo-bucket/demo-repo/*"
            ]
        }
    ]
}</pre>
<div class="section-body-text">
Commands are run exactly as if the repository were stored on a local disk.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create the stanza
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stanza-create</pre>
<pre class="execute-body-output">       [filtered 4 lines of output]
P00   INFO: stanza 'demo' already exists on repo2 and is valid
P00   INFO: stanza-create for stanza 'demo' on repo3</pre>
<pre class="execute-body-output-highlight">P00   INFO: stanza-create command end: completed successfully</pre>
</div></div><div class="section-body-text">
File creation time in S3 is relatively slow so <span class="cmd">backup</span>/<span class="cmd">restore</span> performance is improved by enabling <a href="#backup/bundle">file bundling</a>.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Backup the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --repo=3 \
       --log-level-console=info backup</pre>
<pre class="execute-body-output">P00   INFO: backup command begin 2.55.0: --exec-id=4076-d08c3169 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --repo=3 --repo2-azure-account=<redacted> --repo2-azure-container=demo-container --repo2-azure-key=<redacted> --repo1-block --repo1-bundle --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo3-retention-full=4 --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key=<redacted> --repo3-s3-key-secret=<redacted> --repo3-s3-region=us-east-1 --repo2-type=azure --repo3-type=s3 --stanza=demo --start-fast</pre>
<pre class="execute-body-output-highlight">P00   WARN: no prior backup exists, incr backup has been changed to full</pre>
<pre class="execute-body-output">P00   INFO: execute non-exclusive backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 00000005000000000000001C, lsn = 0/1C000028
       [filtered 3 lines of output]
P00   INFO: check archive for segment(s) 00000005000000000000001C:00000005000000000000001D
P00   INFO: new backup label = 20250421-131433F</pre>
<pre class="execute-body-output-highlight">P00   INFO: full backup size = 30.8MB, file total = 1229</pre>
<pre class="execute-body-output">P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.55.0: --exec-id=4076-d08c3169 --log-level-console=info --no-log-timestamp --repo=3 --repo2-azure-account=<redacted> --repo2-azure-container=demo-container --repo2-azure-key=<redacted> --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo3-retention-full=4 --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key=<redacted> --repo3-s3-key-secret=<redacted> --repo3-s3-region=us-east-1 --repo2-type=azure --repo3-type=s3 --stanza=demo</pre>
</div></div></div></div><div class="section1"><a id="sftp-support"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
SFTP Support
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> supports locating repositories on <span class="host">SFTP</span> hosts. SFTP file transfer is relatively slow so commands benefit by increasing <span class="br-option">process-max</span> to parallelize file transfer.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="host">SFTP</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
process-max=4<br/>
repo1-block=y<br/>
repo1-bundle=y<br/>
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO<br/>
repo1-cipher-type=aes-256-cbc<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-diff=2<br/>
repo1-retention-full=2<br/>
repo2-azure-account=pgbackrest<br/>
repo2-azure-container=demo-container<br/>
repo2-azure-key=YXpLZXk=<br/>
repo2-path=/demo-repo<br/>
repo2-retention-full=4<br/>
repo2-type=azure<br/>
repo3-path=/demo-repo<br/>
repo3-retention-full=4<br/>
repo3-s3-bucket=demo-bucket<br/>
repo3-s3-endpoint=s3.us-east-1.amazonaws.com<br/>
repo3-s3-key=accessKey1<br/>
repo3-s3-key-secret=verySecretKey1<br/>
repo3-s3-region=us-east-1<br/>
repo3-type=s3<br/>
repo4-bundle=y<br/>
repo4-path=/demo-repo<br/>
repo4-sftp-host=sftp-server<br/>
repo4-sftp-host-key-hash-type=sha1<br/>
repo4-sftp-host-user=pgbackrest<br/>
repo4-sftp-private-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp<br/>
repo4-sftp-public-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp.pub<br/>
repo4-type=sftp<br/>
start-fast=y<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div><div class="section-body-text">
When utilizing <span class="host">SFTP</span>, if libssh2 is compiled against OpenSSH then <span class="br-option">repo4-sftp-public-key-file</span> is optional.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Generate SSH keypair for SFTP backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres mkdir -m 750 -p /var/lib/pgsql/.ssh</pre>
<pre class="execute-body-cmd">sudo -u postgres ssh-keygen -f /var/lib/pgsql/.ssh/id_rsa_sftp \
       -t rsa -b 4096 -N "" -m PEM</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">sftp-server</span> <b>&#x21d2;</b> Copy <span class="host">pg-primary</span> SFTP backup public key to <span class="host">sftp-server</span>
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest mkdir -m 750 -p /home/pgbackrest/.ssh</pre>
<pre class="execute-body-cmd">(sudo ssh root@pg-primary cat /var/lib/pgsql/.ssh/id_rsa_sftp.pub) | \
       sudo -u pgbackrest tee -a /home/pgbackrest/.ssh/authorized_keys</pre>
</div></div><div class="section-body-text">
Commands are run exactly as if the repository were stored on a local disk.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Add sftp-server fingerprint to known_hosts file since <span class="br-option">repo4-sftp-host-key-check-type</span> defaults to <q>strict</q>
</div><div class="execute-body">
<pre class="execute-body-cmd">ssh-keyscan -H sftp-server >> /var/lib/pgsql/.ssh/known_hosts 2>/dev/null</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create the stanza
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --log-level-console=info stanza-create</pre>
<pre class="execute-body-output">       [filtered 6 lines of output]
P00   INFO: stanza 'demo' already exists on repo3 and is valid
P00   INFO: stanza-create for stanza 'demo' on repo4</pre>
<pre class="execute-body-output-highlight">P00   INFO: stanza-create command end: completed successfully</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Backup the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --repo=4 \
       --log-level-console=info backup</pre>
<pre class="execute-body-output">P00   INFO: backup command begin 2.55.0: --exec-id=4309-3d23f2f1 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --process-max=4 --repo=4 --repo2-azure-account=<redacted> --repo2-azure-container=demo-container --repo2-azure-key=<redacted> --repo1-block --repo1-bundle --repo4-bundle --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo4-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo3-retention-full=4 --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key=<redacted> --repo3-s3-key-secret=<redacted> --repo3-s3-region=us-east-1 --repo4-sftp-host=sftp-server --repo4-sftp-host-key-hash-type=sha1 --repo4-sftp-host-user=pgbackrest --repo4-sftp-private-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp --repo4-sftp-public-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp.pub --repo2-type=azure --repo3-type=s3 --repo4-type=sftp --stanza=demo --start-fast
P00   WARN: option 'repo4-retention-full' is not set for 'repo4-retention-full-type=count', the repository may run out of space
            HINT: to retain full backups indefinitely (without warning), set option 'repo4-retention-full' to the maximum.</pre>
<pre class="execute-body-output-highlight">P00   WARN: no prior backup exists, incr backup has been changed to full</pre>
<pre class="execute-body-output">P00   INFO: execute non-exclusive backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 00000005000000000000001E, lsn = 0/1E000028
       [filtered 3 lines of output]
P00   INFO: check archive for segment(s) 00000005000000000000001E:00000005000000000000001F
P00   INFO: new backup label = 20250421-131443F</pre>
<pre class="execute-body-output-highlight">P00   INFO: full backup size = 30.8MB, file total = 1229</pre>
<pre class="execute-body-output">P00   INFO: backup command end: completed successfully
P00   INFO: expire command begin 2.55.0: --exec-id=4309-3d23f2f1 --log-level-console=info --no-log-timestamp --repo=4 --repo2-azure-account=<redacted> --repo2-azure-container=demo-container --repo2-azure-key=<redacted> --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo4-path=/demo-repo --repo1-retention-diff=2 --repo1-retention-full=2 --repo2-retention-full=4 --repo3-retention-full=4 --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key=<redacted> --repo3-s3-key-secret=<redacted> --repo3-s3-region=us-east-1 --repo4-sftp-host=sftp-server --repo4-sftp-host-key-hash-type=sha1 --repo4-sftp-host-user=pgbackrest --repo4-sftp-private-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp --repo4-sftp-public-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp.pub --repo2-type=azure --repo3-type=s3 --repo4-type=sftp --stanza=demo
P00   INFO: expire command end: completed successfully</pre>
</div></div></div></div><div class="section1"><a id="gcs-support"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
GCS-Compatible Object Store Support
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> supports locating repositories in <span class="host">GCS-compatible</span> object stores. The bucket used to store the repository must be created in advance &mdash; <span class="backrest">pgBackRest</span> will not do it automatically. The repository can be located in the bucket root (<span class="path">/</span>) but it's usually best to place it in a subpath so object store logs or other data can also be stored in the bucket without conflicts.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="host">GCS</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
process-max=4<br/>
repo1-block=y<br/>
repo1-bundle=y<br/>
repo1-cipher-pass=zWaf6XtpjIVZC5444yXB+cgFDFl7MxGlgkZSaoPvTGirhPygu4jOKOXf9LO4vjfO<br/>
repo1-cipher-type=aes-256-cbc<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-diff=2<br/>
repo1-retention-full=2<br/>
repo2-azure-account=pgbackrest<br/>
repo2-azure-container=demo-container<br/>
repo2-azure-key=YXpLZXk=<br/>
repo2-path=/demo-repo<br/>
repo2-retention-full=4<br/>
repo2-type=azure<br/>
repo3-path=/demo-repo<br/>
repo3-retention-full=4<br/>
repo3-s3-bucket=demo-bucket<br/>
repo3-s3-endpoint=s3.us-east-1.amazonaws.com<br/>
repo3-s3-key=accessKey1<br/>
repo3-s3-key-secret=verySecretKey1<br/>
repo3-s3-region=us-east-1<br/>
repo3-type=s3<br/>
repo4-bundle=y<br/>
repo4-path=/demo-repo<br/>
repo4-sftp-host=sftp-server<br/>
repo4-sftp-host-key-hash-type=sha1<br/>
repo4-sftp-host-user=pgbackrest<br/>
repo4-sftp-private-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp<br/>
repo4-sftp-public-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp.pub<br/>
repo4-type=sftp<br/>
repo5-gcs-bucket=demo-bucket<br/>
repo5-gcs-key=/etc/pgbackrest/gcs-key.json<br/>
repo5-path=/demo-repo<br/>
repo5-type=gcs<br/>
start-fast=y<br/>
<br/>
[global:archive-push]<br/>
compress-level=3
</div></div></div><div class="section-body-text">
When running in <span class="host">GCE</span> set <span class="br-option">repo5-gcs-key-type=auto</span> to automatically authenticate using the instance service account.
</div><div class="section-body-text">
Commands are run exactly as if the repository were stored on a local disk.
</div><div class="section-body-text">
File creation time in GCS is relatively slow so <span class="cmd">backup</span>/<span class="cmd">restore</span> performance is improved by enabling <a href="#backup/bundle">file bundling</a>.
</div></div></div><div class="section1"><a id="repo-target-time"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Target Time for Repository
</div></div><div class="section-body"><div class="section-body-text">
The target time defines the time that commands use to read a repository on versioned storage. This allows the command to read the repository as it was at a point-in-time in order to recover data that has been deleted or corrupted by user accident or malware.<br/>
<br/>
Versioned storage is supported by <span class="host">S3</span>, <span class="host">GCS</span>, and <span class="host">Azure</span> but is generally not enabled by default. In addition to enabling versioning, it may be useful to enable object locking for <span class="host">S3</span> and soft delete for <span class="host">GCS</span> or <span class="host">Azure</span>.<br/>
<br/>
When the <span class="br-option">repo-target-time</span> option is specified then the <span class="br-option">repo</span> option must also be provided. It is likely that not all repository types will support versioning and in general it makes sense to target a single repository for recovery.<br/>
<br/>
Note that comparisons to the storage timestamp are <= the timestamp provided and milliseconds are truncated from the timestamp when provided.
</div><div class="section-body-text">
To demonstrate this feature the <span class="id">demo</span> stanza in the <span class="host">S3</span> repo is deleted.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Delete stanza in <span class="host">S3</span> repository
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl stop postgresql-13.service</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo stop</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --repo=3 stanza-delete</pre>
</div></div><div class="section-body-text">
Once the stanza is deleted the <span class="cmd">info</span> command will show the repository in an error state.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Error on info
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --repo=3 info</pre>
<pre class="execute-body-output">stanza: demo</pre>
<pre class="execute-body-output-highlight">    status: error (missing stanza data)</pre>
<pre class="execute-body-output">    cipher: none</pre>
</div></div><div class="section-body-text">
However, since the storage is versioned, it is possible to look at the repository at a time before the stanza was deleted. Finding the target time can be tricky depending on the situation, but in this case the time when the stanza was deleted can be determined by checking when <span class="file">backup.info</span> was deleted.
</div><div class="execute"><div class="execute-title">
<span class="host">s3-server</span> <b>&#x21d2;</b> Use <span class="id">mc</span> to list versions of <span class="file">backup.info</span> in the bucket
</div><div class="execute-body">
<pre class="execute-body-cmd">mc ls --versions s3/demo-bucket/demo-repo/backup/demo/backup.info</pre>
<pre class="execute-body-output-highlight">[2025-04-21 13:14:52 UTC]     0B STANDARD 87e00a49-cfe8-4978-947f-9a557f039513 v3 DEL backup.info
[2025-04-21 13:14:40 UTC] 1.0KiB STANDARD 908ea7a5-a84f-4b0d-88cb-c8b17e6c0290 v2 PUT backup.info
[2025-04-21 13:14:33 UTC]   372B STANDARD 149d2def-0871-48c7-ba6f-6bad83a9afd4 v1 PUT backup.info</pre>
<pre class="execute-body-output">[2025-04-21 13:14:52 UTC]     0B STANDARD 05a26eec-7460-419f-9397-6444fae38507 v3 DEL backup.info.copy
[2025-04-21 13:14:40 UTC] 1.0KiB STANDARD 4369ef03-d0bd-4e29-8342-03d757acba14 v2 PUT backup.info.copy</pre>
</div></div><div class="section-body-text">
Now the <span class="cmd">info</span> command can be run with a target time that will show the repository before it was deleted.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Info with target time
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --repo=3 \
       --repo-target-time="2025-04-21 13:14:40+00" info</pre>
<pre class="execute-body-output">       [filtered 5 lines of output]
        wal archive min/max (13): 00000005000000000000001C/00000005000000000000001D
</pre>
<pre class="execute-body-output-highlight">        full backup: 20250421-131433F</pre>
<pre class="execute-body-output">            timestamp start/stop: 2025-04-21 13:14:33+00 / 2025-04-21 13:14:39+00
            wal start/stop: 00000005000000000000001C / 00000005000000000000001D
            repo3: backup set size: 3.8MB, backup size: 3.8MB</pre>
</div></div><div class="section-body-text">
If the required backup is shown by the <span class="cmd">info</span> command then it can be restored using the same target time.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Restore with target time
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --repo=3 --delta \
       --repo-target-time="2025-04-21 13:14:40+00" --log-level-console=info restore</pre>
<pre class="execute-body-output">P00   INFO: restore command begin 2.55.0: --delta --exec-id=4541-34fb8277 --log-level-console=info --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --process-max=4 --repo=3 --repo2-azure-account=<redacted> --repo2-azure-container=demo-container --repo2-azure-key=<redacted> --repo1-cipher-pass=<redacted> --repo1-cipher-type=aes-256-cbc --repo5-gcs-bucket=demo-bucket --repo5-gcs-key=<redacted> --repo1-path=/var/lib/pgbackrest --repo2-path=/demo-repo --repo3-path=/demo-repo --repo4-path=/demo-repo --repo5-path=/demo-repo --repo3-s3-bucket=demo-bucket --repo3-s3-endpoint=s3.us-east-1.amazonaws.com --repo3-s3-key=<redacted> --repo3-s3-key-secret=<redacted> --repo3-s3-region=us-east-1 --repo4-sftp-host=sftp-server --repo4-sftp-host-key-hash-type=sha1 --repo4-sftp-host-user=pgbackrest --repo4-sftp-private-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp --repo4-sftp-public-key-file=/var/lib/pgsql/.ssh/id_rsa_sftp.pub --repo-target-time="2025-04-21 13:14:40+00" --repo2-type=azure --repo3-type=s3 --repo4-type=sftp --repo5-type=gcs --stanza=demo</pre>
<pre class="execute-body-output-highlight">P00   INFO: repo3: restore backup set 20250421-131433F, recovery will start at 2025-04-21 13:14:33</pre>
<pre class="execute-body-output">P00   INFO: remove invalid files/links/paths from '/var/lib/pgsql/13/data'
P00   INFO: write updated /var/lib/pgsql/13/data/postgresql.auto.conf
       [filtered 2 lines of output]</pre>
<pre class="execute-body-cmd">sudo systemctl start postgresql-13.service</pre>
</div></div></div></div><div class="section1"><a id="repo-host"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Dedicated Repository Host
</div></div><div class="section-body"><div class="section-body-text">
The configuration described in <a href="#quickstart">Quickstart</a> is suitable for simple installations but for enterprise configurations it is more typical to have a dedicated <span class="host">repository</span> host where the backups and WAL archive files are stored. This separates the backups and WAL archive from the database server so <span class="host">database</span> host failures have less impact. It is still a good idea to employ traditional backup software to backup the <span class="host">repository</span> host.
</div><div class="section-body-text">
On <span class="postgres">PostgreSQL</span> hosts, <span class="br-option">pg1-path</span> is required to be the path of the local PostgreSQL cluster and no <span class="br-option">pg1-host</span> should be configured. When configuring a repository host, the pgbackrest configuration file must have the <span class="br-option">pg-host</span> option configured to connect to the primary and standby (if any) hosts. The repository host has the only pgbackrest configuration that should be aware of more than one <span class="postgres">PostgreSQL</span> host. Order does not matter, e.g. pg1-path/pg1-host, pg2-path/pg2-host can be primary or standby.
</div><div class="section2"><a id="repo-host/install"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Installation
</div></div><div class="section-body"><div class="section-body-text">
A new host named <span class="host">repository</span> is created to store the cluster backups.
</div><div class="admonition"><div class="note">
NOTE:
</div><div class="note-text">
The <span class="backrest">pgBackRest</span> version installed on the <span class="host">repository</span> host must exactly match the version installed on the <span class="postgres">PostgreSQL</span> host.
</div></div><div class="section-body-text">
The <span class="user">pgbackrest</span> user is created to own the <span class="backrest">pgBackRest</span> repository. Any user can own the repository but it is best not to use <span class="user">postgres</span> (if it exists) to avoid confusion.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Create <span class="user">pgbackrest</span> user
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo groupadd pgbackrest</pre>
<pre class="execute-body-cmd">sudo adduser -gpgbackrest -n pgbackrest</pre>
</div></div><div class="section-body-text">
Installing <span class="backrest">pgBackRest</span> from a package is preferable to building from source. When installing from a package the rest of the instructions in this section are generally not required, but it is possible that a package will skip creating one of the directories or apply incorrect permissions. In that case it may be necessary to manually create directories or update permissions.
</div><div class="section-body-text">
RHEL packages for <span class="backrest">pgBackRest</span> are available from <a href="http://www.crunchydata.com">Crunchy Data</a> or <a href="http://yum.postgresql.org">yum.postgresql.org</a>.
</div><div class="section-body-text">
If packages are not provided for your distribution/version you can <a href="#build">build from source</a> and then install manually as shown here.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Install dependencies
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo yum install postgresql-libs libssh2</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Copy <span class="backrest">pgBackRest</span> binary from build host
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo scp build:/build/pgbackrest/src/pgbackrest /usr/bin</pre>
<pre class="execute-body-cmd">sudo chmod 755 /usr/bin/pgbackrest</pre>
</div></div><div class="section-body-text">
<span class="backrest">pgBackRest</span> requires log and configuration directories and a configuration file.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Create <span class="backrest">pgBackRest</span> configuration file and directories
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo mkdir -p -m 770 /var/log/pgbackrest</pre>
<pre class="execute-body-cmd">sudo chown pgbackrest:pgbackrest /var/log/pgbackrest</pre>
<pre class="execute-body-cmd">sudo mkdir -p /etc/pgbackrest</pre>
<pre class="execute-body-cmd">sudo mkdir -p /etc/pgbackrest/conf.d</pre>
<pre class="execute-body-cmd">sudo touch /etc/pgbackrest/pgbackrest.conf</pre>
<pre class="execute-body-cmd">sudo chmod 640 /etc/pgbackrest/pgbackrest.conf</pre>
<pre class="execute-body-cmd">sudo chown pgbackrest:pgbackrest /etc/pgbackrest/pgbackrest.conf</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Create the <span class="backrest">pgBackRest</span> repository
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo mkdir -p /var/lib/pgbackrest</pre>
<pre class="execute-body-cmd">sudo chmod 750 /var/lib/pgbackrest</pre>
<pre class="execute-body-cmd">sudo chown pgbackrest:pgbackrest /var/lib/pgbackrest</pre>
</div></div></div></div><div class="section2"><a id="repo-host/config"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Configuration
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> can use TLS with client certificates to enable communication between the hosts. It is also possible to use SSH, see <a href="user-guide.html#repo-host/setup-ssh">Setup SSH</a>.
</div><div class="section-body-text">
<span class="backrest">pgBackRest</span> expects client/server certificates to be generated in the same way as <span class="postgres">PostgreSQL</span>. See <a href="https://www.postgresql.org/docs/current/ssl-tcp.html">Secure TCP/IP Connections with TLS</a> for detailed instructions on generating certificates.
</div><div class="section-body-text">
The <span class="host">repository</span> host must be configured with the <span class="host">pg-primary</span> host/user and database path. The primary will be configured as <span class="id">pg1</span> to allow a standby to be added later.
</div><div class="config"><div class="config-title">
<span class="host">repository</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="br-option">pg1-host</span>/<span class="br-option">pg1-host-user</span> and <span class="br-option">pg1-path</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-host=pg-primary<br/>
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg1-host-type=tls<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-full=2<br/>
start-fast=y<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=*<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key
</div></div></div><div class="section-body-text">
The database host must be configured with the repository host/user. The default for the <span class="br-option">repo1-host-user</span> option is <span class="id">pgbackrest</span>. If the <span class="id">postgres</span> user does restores on the repository host it is best not to also allow the <span class="id">postgres</span> user to perform backups. However, the <span class="id">postgres</span> user can read the repository directly if it is in the same group as the <span class="id">pgbackrest</span> user.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="br-option">repo1-host</span>/<span class="br-option">repo1-host-user</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
log-level-file=detail<br/>
repo1-host=repository<br/>
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
repo1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
repo1-host-type=tls<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=demo<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key
</div></div></div><div class="section-body-text">
<span class="postgres">PostgreSQL</span> configuration may be found in the <a href="#quickstart/configure-archiving">Configure Archiving</a> section.
</div><div class="section-body-text">
Commands are run the same as on a single host configuration except that some commands such as <span class="cmd">backup</span> and <span class="cmd">expire</span> are run from the <span class="host">repository</span> host instead of the <span class="host">database</span> host.
</div></div></div><div class="section2"><a id="repo-host/setup-tls"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Setup TLS Server
</div></div><div class="section-body"><div class="section-body-text">
The <span class="backrest">pgBackRest</span> TLS server must be configured and started on each host.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Setup pgBackRest Server
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo cat /etc/systemd/system/pgbackrest.service</pre>
<pre class="execute-body-output">[Unit]
Description=pgBackRest Server
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=pgbackrest
ExecStart=/usr/bin/pgbackrest server
ExecStartPost=/bin/sleep 3
ExecStartPost=/bin/bash -c "[ ! -z $MAINPID ]"
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target</pre>
<pre class="execute-body-cmd">sudo systemctl enable pgbackrest</pre>
<pre class="execute-body-cmd">sudo systemctl start pgbackrest</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Setup pgBackRest Server
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo cat /etc/systemd/system/pgbackrest.service</pre>
<pre class="execute-body-output">[Unit]
Description=pgBackRest Server
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=postgres
ExecStart=/usr/bin/pgbackrest server
ExecStartPost=/bin/sleep 3
ExecStartPost=/bin/bash -c "[ ! -z $MAINPID ]"
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target</pre>
<pre class="execute-body-cmd">sudo systemctl enable pgbackrest</pre>
<pre class="execute-body-cmd">sudo systemctl start pgbackrest</pre>
</div></div></div></div><div class="section2"><a id="repo-host/stanza-create"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Create and Check Stanza
</div></div><div class="section-body"><div class="section-body-text">
Create the stanza in the new repository.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Create the stanza
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest pgbackrest --stanza=demo stanza-create</pre>
</div></div><div class="section-body-text">
Check that the configuration is correct on both the <span class="host">database</span> and <span class="host">repository</span> hosts. More information about the <span class="cmd">check</span> command can be found in <a href="#quickstart/check-configuration">Check the Configuration</a>.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Check the configuration
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo check</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Check the configuration
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest pgbackrest --stanza=demo check</pre>
</div></div></div></div><div class="section2"><a id="repo-host/perform-backup"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Perform a Backup
</div></div><div class="section-body"><div class="section-body-text">
To perform a backup of the <span class="postgres">PostgreSQL</span> cluster run <span class="backrest">pgBackRest</span> with the <span class="cmd">backup</span> command on the <span class="host">repository</span> host.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Backup the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest pgbackrest --stanza=demo backup</pre>
<pre class="execute-body-output">P00   WARN: no prior backup exists, incr backup has been changed to full</pre>
</div></div><div class="section-body-text">
Since a new repository was created on the <span class="host">repository</span> host the warning about the incremental backup changing to a full backup was emitted.
</div></div></div><div class="section2"><a id="repo-host/perform-restore"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Restore a Backup
</div></div><div class="section-body"><div class="section-body-text">
To perform a restore of the <span class="postgres">PostgreSQL</span> cluster run <span class="backrest">pgBackRest</span> with the <span class="cmd">restore</span> command on the <span class="host">database</span> host.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Stop the demo cluster, restore, and restart <span class="postgres">PostgreSQL</span>
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl stop postgresql-13.service</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --delta restore</pre>
<pre class="execute-body-cmd">sudo systemctl start postgresql-13.service</pre>
</div></div></div></div></div></div><div class="section1"><a id="parallel-backup-restore"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Parallel Backup / Restore
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> offers parallel processing to improve performance of compression and transfer. The number of processes to be used for this feature is set using the <span class="br-option">--process-max</span> option.
</div><div class="section-body-text">
It is usually best not to use more than 25% of available CPUs for the <span class="cmd">backup</span> command. Backups don't have to run that fast as long as they are performed regularly and the backup process should not impact database performance, if at all possible.
</div><div class="section-body-text">
The restore command can and should use all available CPUs because during a restore the <span class="postgres">PostgreSQL</span> cluster is shut down and there is generally no other important work being done on the host. If the host contains multiple clusters then that should be considered when setting restore parallelism.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Perform a backup with single process
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest pgbackrest --stanza=demo --type=full backup</pre>
</div></div><div class="config"><div class="config-title">
<span class="host">repository</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="backrest">pgBackRest</span> to use multiple <span class="cmd">backup</span> processes
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-host=pg-primary<br/>
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg1-host-type=tls<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
process-max=3<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-full=2<br/>
start-fast=y<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=*<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key
</div></div></div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Perform a backup with multiple processes
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest pgbackrest --stanza=demo --type=full backup</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Get backup info for the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest pgbackrest info</pre>
<pre class="execute-body-output">stanza: demo
    status: ok
    cipher: none

    db (current)
        wal archive min/max (13): 000000070000000000000023/000000070000000000000025

        full backup: 20250421-131610F</pre>
<pre class="execute-body-output-highlight">            timestamp start/stop: 2025-04-21 13:16:10+00 / 2025-04-21 13:16:14+00</pre>
<pre class="execute-body-output">            wal start/stop: 000000070000000000000023 / 000000070000000000000023
            database size: 30.8MB, database backup size: 30.8MB
            repo1: backup set size: 3.8MB, backup size: 3.8MB

        full backup: 20250421-131615F</pre>
<pre class="execute-body-output-highlight">            timestamp start/stop: 2025-04-21 13:16:15+00 / 2025-04-21 13:16:19+00</pre>
<pre class="execute-body-output">            wal start/stop: 000000070000000000000024 / 000000070000000000000025
            database size: 30.8MB, database backup size: 30.8MB
            repo1: backup set size: 3.8MB, backup size: 3.8MB</pre>
</div></div><div class="section-body-text">
The performance of the last backup should be improved by using multiple processes. For very small backups the difference may not be very apparent, but as the size of the database increases so will time savings.
</div></div></div><div class="section1"><a id="start-stop"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Starting and Stopping
</div></div><div class="section-body"><div class="section-body-text">
If a standby is promoted for testing, or a test cluster is restored from a production backup, then it is a good idea to prevent those clusters from writing to <span class="backrest">pgBackRest</span> repositories. This can be accomplished with the <span class="cmd">stop</span> command.
</div><div class="section-body-text">
The commands that write and are blocked by <span class="cmd">stop</span> are: <span class="cmd">archive-push</span>, <span class="cmd">backup</span>, <span class="cmd">expire</span>, <span class="cmd">stanza-create</span>, and <span class="cmd">stanza-upgrade</span>. Note that <span class="cmd">stanza-delete</span> is an exception to this rule (see <a href="#delete-stanza">Delete a Stanza</a> for more details).
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Stop <span class="backrest">pgBackRest</span> write commands
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest stop</pre>
</div></div><div class="section-body-text">
New <span class="backrest">pgBackRest</span> write commands will no longer run.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Attempt a backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest pgbackrest --stanza=demo backup</pre>
<pre class="execute-body-output-highlight-error">P00   WARN: unable to check pg1: [StopError] raised from remote-0 tls protocol on 'pg-primary': stop file exists for all stanzas</pre>
<pre class="execute-body-output">P00  ERROR: [056]: unable to find primary cluster - cannot proceed
            HINT: are all available clusters in recovery?</pre>
</div></div><div class="section-body-text">
Specify the <span class="br-option">--force</span> option to terminate any <span class="backrest">pgBackRest</span> write commands that are currently running. This includes asynchronous archive-get (though it will run again if <span class="postgres">PostgreSQL</span> requires it). If <span class="backrest">pgBackRest</span> is already stopped then stopping again will generate a warning.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Stop the <span class="backrest">pgBackRest</span> services again
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest stop</pre>
<pre class="execute-body-output">P00   WARN: stop file already exists for all stanzas</pre>
</div></div><div class="section-body-text">
Start <span class="backrest">pgBackRest</span> write commands again with the <span class="cmd">start</span> command. Write commands that were in progress before the stop will not automatically start again, but they are now allowed to start.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Start <span class="backrest">pgBackRest</span> write commands
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest start</pre>
</div></div><div class="section-body-text">
It is also possible to stop <span class="backrest">pgBackRest</span> for a single stanza.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Stop <span class="backrest">pgBackRest</span> write commands for the <span class="id">demo</span> stanza
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo stop</pre>
</div></div><div class="section-body-text">
New <span class="backrest">pgBackRest</span> write commands for the specified stanza will no longer run.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Attempt a backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest pgbackrest --stanza=demo backup</pre>
<pre class="execute-body-output-highlight-error">P00   WARN: unable to check pg1: [StopError] raised from remote-0 tls protocol on 'pg-primary': stop file exists for stanza demo</pre>
<pre class="execute-body-output">P00  ERROR: [056]: unable to find primary cluster - cannot proceed
            HINT: are all available clusters in recovery?</pre>
</div></div><div class="section-body-text">
The stanza must also be specified when starting <span class="backrest">pgBackRest</span> write commands for a single stanza.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Start <span class="backrest">pgBackRest</span> write commands for the <span class="id">demo</span> stanza
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo start</pre>
</div></div></div></div><div class="section1"><a id="replication"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Replication
</div></div><div class="section-body"><div class="section-body-text">
Replication allows multiple copies of a <span class="postgres">PostgreSQL</span> cluster (called standbys) to be created from a single primary. The standbys are useful for balancing reads and to provide redundancy in case the primary host fails.
</div><div class="section2"><a id="replication/installation"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Installation
</div></div><div class="section-body"><div class="section-body-text">
A new host named <span class="host">pg-standby</span> is created to run the standby.
</div><div class="section-body-text">
Installing <span class="backrest">pgBackRest</span> from a package is preferable to building from source. When installing from a package the rest of the instructions in this section are generally not required, but it is possible that a package will skip creating one of the directories or apply incorrect permissions. In that case it may be necessary to manually create directories or update permissions.
</div><div class="section-body-text">
RHEL packages for <span class="backrest">pgBackRest</span> are available from <a href="http://www.crunchydata.com">Crunchy Data</a> or <a href="http://yum.postgresql.org">yum.postgresql.org</a>.
</div><div class="section-body-text">
If packages are not provided for your distribution/version you can <a href="#build">build from source</a> and then install manually as shown here.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Install dependencies
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo yum install postgresql-libs libssh2</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Copy <span class="backrest">pgBackRest</span> binary from build host
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo scp build:/build/pgbackrest/src/pgbackrest /usr/bin</pre>
<pre class="execute-body-cmd">sudo chmod 755 /usr/bin/pgbackrest</pre>
</div></div><div class="section-body-text">
<span class="backrest">pgBackRest</span> requires log and configuration directories and a configuration file.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Create <span class="backrest">pgBackRest</span> configuration file and directories
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo mkdir -p -m 770 /var/log/pgbackrest</pre>
<pre class="execute-body-cmd">sudo chown postgres:postgres /var/log/pgbackrest</pre>
<pre class="execute-body-cmd">sudo mkdir -p /etc/pgbackrest</pre>
<pre class="execute-body-cmd">sudo mkdir -p /etc/pgbackrest/conf.d</pre>
<pre class="execute-body-cmd">sudo touch /etc/pgbackrest/pgbackrest.conf</pre>
<pre class="execute-body-cmd">sudo chmod 640 /etc/pgbackrest/pgbackrest.conf</pre>
<pre class="execute-body-cmd">sudo chown postgres:postgres /etc/pgbackrest/pgbackrest.conf</pre>
</div></div></div></div><div class="section2"><a id="replication/hot-standby"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Hot Standby
</div></div><div class="section-body"><div class="section-body-text">
A hot standby performs replication using the WAL archive and allows read-only queries.
</div><div class="section-body-text">
<span class="backrest">pgBackRest</span> configuration is very similar to <span class="host">pg-primary</span> except that the <span class="id">standby</span> recovery type will be used to keep the cluster in recovery mode when the end of the WAL stream has been reached.
</div><div class="config"><div class="config-title">
<span class="host">pg-standby</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="backrest">pgBackRest</span> on the standby
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
log-level-file=detail<br/>
repo1-host=repository<br/>
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
repo1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
repo1-host-type=tls<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=demo<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key
</div></div></div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Setup pgBackRest Server
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo cat /etc/systemd/system/pgbackrest.service</pre>
<pre class="execute-body-output">[Unit]
Description=pgBackRest Server
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=postgres
ExecStart=/usr/bin/pgbackrest server
ExecStartPost=/bin/sleep 3
ExecStartPost=/bin/bash -c "[ ! -z $MAINPID ]"
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target</pre>
<pre class="execute-body-cmd">sudo systemctl enable pgbackrest</pre>
<pre class="execute-body-cmd">sudo systemctl start pgbackrest</pre>
</div></div><div class="section-body-text">
Create the path where <span class="postgres">PostgreSQL</span> will be restored.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Create <span class="postgres">PostgreSQL</span> path
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres mkdir -p -m 700 /var/lib/pgsql/13/data</pre>
</div></div><div class="section-body-text">
Now the standby can be created with the <span class="cmd">restore</span> command.
</div><div class="admonition"><div class="important">
IMPORTANT:
</div><div class="important-text">
If the cluster is intended to be promoted without becoming the new primary (e.g. for reporting or testing), use <span class="br-option">--archive-mode=off</span> or set <span class="pg-option">archive_mode=off</span> in <span class="file">postgresql.conf</span> to disable archiving. If archiving is not disabled then the repository may be polluted with WAL that can make restores more difficult.
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Restore the demo standby cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --type=standby restore</pre>
<pre class="execute-body-cmd">sudo -u postgres cat /var/lib/pgsql/13/data/postgresql.auto.conf</pre>
<pre class="execute-body-output"># Do not edit this file manually!
# It will be overwritten by the ALTER SYSTEM command.

# Recovery settings generated by pgBackRest restore on 2025-04-21 13:13:06
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2025-04-21 13:13:37
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2025-04-21 13:14:05
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'
# Removed by pgBackRest restore on 2025-04-21 13:14:55 # recovery_target_time = '2025-04-21 13:13:56.887384+00'
# Removed by pgBackRest restore on 2025-04-21 13:14:55 # recovery_target_action = 'promote'

# Recovery settings generated by pgBackRest restore on 2025-04-21 13:14:55
restore_command = 'pgbackrest --repo=3 --repo-target-time="2025-04-21 13:14:40+00" --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2025-04-21 13:16:05
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2025-04-21 13:17:16
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'</pre>
</div></div><div class="section-body-text">
The <span class="pg-setting">hot_standby</span> setting must be enabled before starting <span class="postgres">PostgreSQL</span> to allow read-only connections on <span class="host">pg-standby</span>. Otherwise, connection attempts will be refused. The rest of the configuration is in case the standby is promoted to a primary.
</div><div class="config"><div class="config-title">
<span class="host">pg-standby</span>:<span class="file">/var/lib/pgsql/13/data/postgresql.conf</span> <b>&#x21d2;</b> Configure <span class="postgres">PostgreSQL</span>
</div><div class="config-body"><div class="config-body-output">
archive_command = 'pgbackrest --stanza=demo archive-push %p'<br/>
archive_mode = on<br/>
hot_standby = on<br/>
log_filename = 'postgresql.log'<br/>
max_wal_senders = 3<br/>
wal_level = replica
</div></div></div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Start <span class="postgres">PostgreSQL</span>
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl start postgresql-13.service</pre>
</div></div><div class="section-body-text">
The <span class="postgres">PostgreSQL</span> log gives valuable information about the recovery. Note especially that the cluster has entered standby mode and is ready to accept read-only connections.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Examine the <span class="postgres">PostgreSQL</span> log output for log messages indicating success
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres cat /var/lib/pgsql/13/data/log/postgresql.log</pre>
<pre class="execute-body-output">       [filtered 4 lines of output]
LOG:  listening on Unix socket "/tmp/.s.PGSQL.5432"
LOG:  database system was interrupted; last known up at 2025-04-21 13:16:15 UTC</pre>
<pre class="execute-body-output-highlight">LOG:  entering standby mode</pre>
<pre class="execute-body-output">LOG:  restored log file "00000007.history" from archive
LOG:  restored log file "000000070000000000000024" from archive
LOG:  redo starts at 0/24000028
LOG:  restored log file "000000070000000000000025" from archive
LOG:  consistent recovery state reached at 0/25000050</pre>
<pre class="execute-body-output-highlight">LOG:  database system is ready to accept read only connections</pre>
</div></div><div class="section-body-text">
An easy way to test that replication is properly configured is to create a table on <span class="host">pg-primary</span>.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create a new table on the primary
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c " \
       begin; \
       create table replicated_table (message text); \
       insert into replicated_table values ('Important Data'); \
       commit; \
       select * from replicated_table";</pre>
<pre class="execute-body-output">    message     
----------------</pre>
<pre class="execute-body-output-highlight"> Important Data</pre>
<pre class="execute-body-output">(1 row)</pre>
</div></div><div class="section-body-text">
And then query the same table on <span class="host">pg-standby</span>.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Query new table on the standby
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c "select * from replicated_table;"</pre>
<pre class="execute-body-output-highlight-error">ERROR:  relation "replicated_table" does not exist</pre>
<pre class="execute-body-output">LINE 1: select * from replicated_table;
                      ^</pre>
</div></div><div class="section-body-text">
So, what went wrong? Since <span class="postgres">PostgreSQL</span> is pulling WAL segments from the archive to perform replication, changes won't be seen on the standby until the WAL segment that contains those changes is pushed from <span class="host">pg-primary</span>.
</div><div class="section-body-text">
This can be done manually by calling <span class="id">pg_switch_wal()</span> which pushes the current WAL segment to the archive (a new WAL segment is created to contain further changes).
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Call <span class="id">pg_switch_wal()</span>
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c "select *, current_timestamp from pg_switch_wal()";</pre>
<pre class="execute-body-output"> pg_switch_wal |       current_timestamp       
---------------+-------------------------------
 0/26017738    | 2025-04-21 13:17:23.254782+00
(1 row)</pre>
</div></div><div class="section-body-text">
Now after a short delay the table will appear on <span class="host">pg-standby</span>.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Now the new table exists on the standby (may require a few retries)
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c " \
       select *, current_timestamp from replicated_table"</pre>
<pre class="execute-body-output">    message     |       current_timestamp       
----------------+-------------------------------</pre>
<pre class="execute-body-output-highlight"> Important Data | 2025-04-21 13:17:24.472161+00</pre>
<pre class="execute-body-output">(1 row)</pre>
</div></div><div class="section-body-text">
Check the standby configuration for access to the repository.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Check the configuration
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --log-level-console=info check</pre>
<pre class="execute-body-output">P00   INFO: check command begin 2.55.0: --exec-id=1181-83c0863f --log-level-console=info --log-level-file=detail --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --stanza=demo
P00   INFO: check repo1 (standby)</pre>
<pre class="execute-body-output-highlight">P00   INFO: switch wal not performed because this is a standby</pre>
<pre class="execute-body-output">P00   INFO: check command end: completed successfully</pre>
</div></div></div></div><div class="section2"><a id="replication/streaming"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Streaming Replication
</div></div><div class="section-body"><div class="section-body-text">
Instead of relying solely on the WAL archive, streaming replication makes a direct connection to the primary and applies changes as soon as they are made on the primary. This results in much less lag between the primary and standby.
</div><div class="section-body-text">
Streaming replication requires a user with the replication privilege.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create replication user
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c " \
       create user replicator password 'jw8s0F4' replication";</pre>
<pre class="execute-body-output">CREATE ROLE</pre>
</div></div><div class="section-body-text">
The <span class="file">pg_hba.conf</span> file must be updated to allow the standby to connect as the replication user. Be sure to replace the IP address below with the actual IP address of your <span class="host">pg-standby</span>. A reload will be required after modifying the <span class="file">pg_hba.conf</span> file.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create <span class="file">pg_hba.conf</span> entry for replication user
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres sh -c 'echo \
       "host    replication     replicator      172.17.0.8/32           md5" \
       >> /var/lib/pgsql/13/data/pg_hba.conf'</pre>
<pre class="execute-body-cmd">sudo systemctl reload postgresql-13.service</pre>
</div></div><div class="section-body-text">
The standby needs to know how to contact the primary so the <span class="pg-option">primary_conninfo</span> setting will be configured in <span class="backrest">pgBackRest</span>.
</div><div class="config"><div class="config-title">
<span class="host">pg-standby</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Set <span class="pg-option">primary_conninfo</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
recovery-option=primary_conninfo=host=172.17.0.6 port=5432 user=replicator<br/>
<br/>
[global]<br/>
log-level-file=detail<br/>
repo1-host=repository<br/>
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
repo1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
repo1-host-type=tls<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=demo<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key
</div></div></div><div class="section-body-text">
It is possible to configure a password in the <span class="pg-option">primary_conninfo</span> setting but using a <span class="file">.pgpass</span> file is more flexible and secure.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Configure the replication password in the <span class="file">.pgpass</span> file.
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres sh -c 'echo \
       "172.17.0.6:*:replication:replicator:jw8s0F4" \
       >> /var/lib/pgsql/.pgpass'</pre>
<pre class="execute-body-cmd">sudo -u postgres chmod 600 /var/lib/pgsql/.pgpass</pre>
</div></div><div class="section-body-text">
Now the standby can be created with the <span class="cmd">restore</span> command.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Stop <span class="postgres">PostgreSQL</span> and restore the demo standby cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl stop postgresql-13.service</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --delta --type=standby restore</pre>
<pre class="execute-body-cmd">sudo -u postgres cat /var/lib/pgsql/13/data/postgresql.auto.conf</pre>
<pre class="execute-body-output"># Do not edit this file manually!
# It will be overwritten by the ALTER SYSTEM command.

# Recovery settings generated by pgBackRest restore on 2025-04-21 13:13:06
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2025-04-21 13:13:37
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2025-04-21 13:14:05
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'
# Removed by pgBackRest restore on 2025-04-21 13:14:55 # recovery_target_time = '2025-04-21 13:13:56.887384+00'
# Removed by pgBackRest restore on 2025-04-21 13:14:55 # recovery_target_action = 'promote'

# Recovery settings generated by pgBackRest restore on 2025-04-21 13:14:55
restore_command = 'pgbackrest --repo=3 --repo-target-time="2025-04-21 13:14:40+00" --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2025-04-21 13:16:05
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'

# Recovery settings generated by pgBackRest restore on 2025-04-21 13:17:30
primary_conninfo = 'host=172.17.0.6 port=5432 user=replicator'
restore_command = 'pgbackrest --stanza=demo archive-get %f "%p"'</pre>
</div></div><div class="admonition"><div class="note">
NOTE:
</div><div class="note-text">
The <span class="pg-setting">primary_conninfo</span> setting has been written into the <span class="file">postgresql.auto.conf</span> file because it was configured as a <span class="br-option">recovery-option</span> in <span class="file">pgbackrest.conf</span>. The <span class="br-setting">--type=preserve</span> option can be used with the <span class="cmd">restore</span> to leave the existing <span class="file">postgresql.auto.conf</span> file in place if that behavior is preferred.
</div></div><div class="section-body-text">
By default RHEL stores the <span class="file">postgresql.conf</span> file in the <span class="postgres">PostgreSQL</span> data directory. That means the change made to <span class="file">postgresql.conf</span> was overwritten by the last restore and the <span class="pg-option">hot_standby</span> setting must be enabled again. Other solutions to this problem are to store the <span class="file">postgresql.conf</span> file elsewhere or to enable the <span class="pg-option">hot_standby</span> setting on the <span class="host">pg-primary</span> host where it will be ignored.
</div><div class="config"><div class="config-title">
<span class="host">pg-standby</span>:<span class="file">/var/lib/pgsql/13/data/postgresql.conf</span> <b>&#x21d2;</b> Enable <span class="pg-option">hot_standby</span>
</div><div class="config-body"><div class="config-body-output">
archive_command = 'pgbackrest --stanza=demo archive-push %p'<br/>
archive_mode = on<br/>
hot_standby = on<br/>
log_filename = 'postgresql.log'<br/>
max_wal_senders = 3<br/>
wal_level = replica
</div></div></div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Start <span class="postgres">PostgreSQL</span>
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl start postgresql-13.service</pre>
</div></div><div class="section-body-text">
The <span class="postgres">PostgreSQL</span> log will confirm that streaming replication has started.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Examine the <span class="postgres">PostgreSQL</span> log output for log messages indicating success
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres cat /var/lib/pgsql/13/data/log/postgresql.log</pre>
<pre class="execute-body-output">       [filtered 12 lines of output]
LOG:  database system is ready to accept read only connections
LOG:  restored log file "000000070000000000000026" from archive</pre>
<pre class="execute-body-output-highlight">LOG:  started streaming WAL from primary at 0/27000000 on timeline 7</pre>
</div></div><div class="section-body-text">
Now when a table is created on <span class="host">pg-primary</span> it will appear on <span class="host">pg-standby</span> quickly and without the need to call <span class="id">pg_switch_wal()</span>.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create a new table on the primary
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c " \
       begin; \
       create table stream_table (message text); \
       insert into stream_table values ('Important Data'); \
       commit; \
       select *, current_timestamp from stream_table";</pre>
<pre class="execute-body-output">    message     |       current_timestamp       
----------------+-------------------------------</pre>
<pre class="execute-body-output-highlight"> Important Data | 2025-04-21 13:17:37.632395+00</pre>
<pre class="execute-body-output">(1 row)</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Query table on the standby
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c " \
       select *, current_timestamp from stream_table"</pre>
<pre class="execute-body-output">    message     |       current_timestamp       
----------------+-------------------------------</pre>
<pre class="execute-body-output-highlight"> Important Data | 2025-04-21 13:17:38.039114+00</pre>
<pre class="execute-body-output">(1 row)</pre>
</div></div></div></div></div></div><div class="section1"><a id="multi-stanza"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Multiple Stanzas
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> supports multiple stanzas. The most common usage is sharing a <span class="host">repository</span> host among multiple stanzas.
</div><div class="section2"><a id="multi-stanza/installation"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Installation
</div></div><div class="section-body"><div class="section-body-text">
A new host named <span class="host">pg-alt</span> is created to run the new primary.
</div><div class="section-body-text">
Installing <span class="backrest">pgBackRest</span> from a package is preferable to building from source. When installing from a package the rest of the instructions in this section are generally not required, but it is possible that a package will skip creating one of the directories or apply incorrect permissions. In that case it may be necessary to manually create directories or update permissions.
</div><div class="section-body-text">
RHEL packages for <span class="backrest">pgBackRest</span> are available from <a href="http://www.crunchydata.com">Crunchy Data</a> or <a href="http://yum.postgresql.org">yum.postgresql.org</a>.
</div><div class="section-body-text">
If packages are not provided for your distribution/version you can <a href="#build">build from source</a> and then install manually as shown here.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-alt</span> <b>&#x21d2;</b> Install dependencies
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo yum install postgresql-libs libssh2</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-alt</span> <b>&#x21d2;</b> Copy <span class="backrest">pgBackRest</span> binary from build host
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo scp build:/build/pgbackrest/src/pgbackrest /usr/bin</pre>
<pre class="execute-body-cmd">sudo chmod 755 /usr/bin/pgbackrest</pre>
</div></div><div class="section-body-text">
<span class="backrest">pgBackRest</span> requires log and configuration directories and a configuration file.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-alt</span> <b>&#x21d2;</b> Create <span class="backrest">pgBackRest</span> configuration file and directories
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo mkdir -p -m 770 /var/log/pgbackrest</pre>
<pre class="execute-body-cmd">sudo chown postgres:postgres /var/log/pgbackrest</pre>
<pre class="execute-body-cmd">sudo mkdir -p /etc/pgbackrest</pre>
<pre class="execute-body-cmd">sudo mkdir -p /etc/pgbackrest/conf.d</pre>
<pre class="execute-body-cmd">sudo touch /etc/pgbackrest/pgbackrest.conf</pre>
<pre class="execute-body-cmd">sudo chmod 640 /etc/pgbackrest/pgbackrest.conf</pre>
<pre class="execute-body-cmd">sudo chown postgres:postgres /etc/pgbackrest/pgbackrest.conf</pre>
</div></div></div></div><div class="section2"><a id="multi-stanza/configuration"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Configuration
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> configuration is nearly identical to <span class="host">pg-primary</span> except that the <span class="id">demo-alt</span> stanza will be used so backups and archive will be stored in a separate location.
</div><div class="config"><div class="config-title">
<span class="host">pg-alt</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="backrest">pgBackRest</span> on the new primary
</div><div class="config-body"><div class="config-body-output">
[demo-alt]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
log-level-file=detail<br/>
repo1-host=repository<br/>
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
repo1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
repo1-host-type=tls<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=demo-alt<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key
</div></div></div><div class="config"><div class="config-title">
<span class="host">repository</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="br-option">pg1-host</span>/<span class="br-option">pg1-host-user</span> and <span class="br-option">pg1-path</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-host=pg-primary<br/>
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg1-host-type=tls<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[demo-alt]<br/>
pg1-host=pg-alt<br/>
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg1-host-type=tls<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
process-max=3<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-full=2<br/>
start-fast=y<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=*<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key
</div></div></div><div class="execute"><div class="execute-title">
<span class="host">pg-alt</span> <b>&#x21d2;</b> Setup pgBackRest Server
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo cat /etc/systemd/system/pgbackrest.service</pre>
<pre class="execute-body-output">[Unit]
Description=pgBackRest Server
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=postgres
ExecStart=/usr/bin/pgbackrest server
ExecStartPost=/bin/sleep 3
ExecStartPost=/bin/bash -c "[ ! -z $MAINPID ]"
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target</pre>
<pre class="execute-body-cmd">sudo systemctl enable pgbackrest</pre>
<pre class="execute-body-cmd">sudo systemctl start pgbackrest</pre>
</div></div></div></div><div class="section2"><a id="multi-stanza/setup-demo-cluster"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Setup Demo Cluster
</div></div><div class="section-body"><div class="execute"><div class="execute-title">
<span class="host">pg-alt</span> <b>&#x21d2;</b> Create the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres /usr/pgsql-13/bin/initdb \
       -D /var/lib/pgsql/13/data -k -A peer</pre>
</div></div><div class="config"><div class="config-title">
<span class="host">pg-alt</span>:<span class="file">/var/lib/pgsql/13/data/postgresql.conf</span> <b>&#x21d2;</b> Configure <span class="postgres">PostgreSQL</span> settings
</div><div class="config-body"><div class="config-body-output">
archive_command = 'pgbackrest --stanza=demo-alt archive-push %p'<br/>
archive_mode = on<br/>
log_filename = 'postgresql.log'<br/>
max_wal_senders = 3<br/>
wal_level = replica
</div></div></div><div class="execute"><div class="execute-title">
<span class="host">pg-alt</span> <b>&#x21d2;</b> Start the demo cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl restart postgresql-13.service</pre>
</div></div></div></div><div class="section2"><a id="multi-stanza/create-stanza"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Create the Stanza and Check Configuration
</div></div><div class="section-body"><div class="section-body-text">
The <span class="cmd">stanza-create</span> command must be run to initialize the stanza. It is recommended that the <span class="cmd">check</span> command be run after <span class="cmd">stanza-create</span> to ensure archiving and backups are properly configured.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-alt</span> <b>&#x21d2;</b> Create the stanza and check the configuration
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo-alt --log-level-console=info stanza-create</pre>
<pre class="execute-body-output">P00   INFO: stanza-create command begin 2.55.0: --exec-id=947-b37a53d9 --log-level-console=info --log-level-file=detail --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --stanza=demo-alt
P00   INFO: stanza-create for stanza 'demo-alt' on repo1</pre>
<pre class="execute-body-output-highlight">P00   INFO: stanza-create command end: completed successfully</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --log-level-console=info check</pre>
<pre class="execute-body-output">P00   INFO: check command begin 2.55.0: --exec-id=974-2b58c025 --log-level-console=info --log-level-file=detail --no-log-timestamp --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls</pre>
<pre class="execute-body-output-highlight">P00   INFO: check stanza 'demo-alt'</pre>
<pre class="execute-body-output">P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)</pre>
<pre class="execute-body-output-highlight">P00   INFO: WAL segment 000000010000000000000001 successfully archived to '/var/lib/pgbackrest/archive/demo-alt/13-1/0000000100000000/000000010000000000000001-29488ff35f82cacada9829c78d94ee2e32ee1348.gz' on repo1</pre>
<pre class="execute-body-output">P00   INFO: check command end: completed successfully</pre>
</div></div><div class="section-body-text">
If the <span class="cmd">check</span> command is run from the <span class="host">repository</span> host then all stanzas will be checked.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Check the configuration for all stanzas
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest pgbackrest --log-level-console=info check</pre>
<pre class="execute-body-output">P00   INFO: check command begin 2.55.0: --exec-id=1315-e00697ae --log-level-console=info --no-log-timestamp --repo1-path=/var/lib/pgbackrest</pre>
<pre class="execute-body-output-highlight">P00   INFO: check stanza 'demo'</pre>
<pre class="execute-body-output">P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)</pre>
<pre class="execute-body-output-highlight">P00   INFO: WAL segment 000000070000000000000027 successfully archived to '/var/lib/pgbackrest/archive/demo/13-1/0000000700000000/000000070000000000000027-169f61cb3767208eadc5ca574c2e239df78a7a19.gz' on repo1
P00   INFO: check stanza 'demo-alt'</pre>
<pre class="execute-body-output">P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)</pre>
<pre class="execute-body-output-highlight">P00   INFO: WAL segment 000000010000000000000002 successfully archived to '/var/lib/pgbackrest/archive/demo-alt/13-1/0000000100000000/000000010000000000000002-28405895feb2380d58e61593cfe240092dd889d0.gz' on repo1</pre>
<pre class="execute-body-output">P00   INFO: check command end: completed successfully</pre>
</div></div></div></div></div></div><div class="section1"><a id="async-archiving"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Asynchronous Archiving
</div></div><div class="section-body"><div class="section-body-text">
Asynchronous archiving is enabled with the <span class="br-option">archive-async</span> option. This option enables asynchronous operation for both the <span class="cmd">archive-push</span> and <span class="cmd">archive-get</span> commands.
</div><div class="section-body-text">
A spool path is required. The commands will store transient data here but each command works quite a bit differently so spool path usage is described in detail in each section.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create the spool directory
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo mkdir -p -m 750 /var/spool/pgbackrest</pre>
<pre class="execute-body-cmd">sudo chown postgres:postgres /var/spool/pgbackrest</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Create the spool directory
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo mkdir -p -m 750 /var/spool/pgbackrest</pre>
<pre class="execute-body-cmd">sudo chown postgres:postgres /var/spool/pgbackrest</pre>
</div></div><div class="section-body-text">
The spool path must be configured and asynchronous archiving enabled. Asynchronous archiving automatically confers some benefit by reducing the number of connections made to remote storage, but setting <span class="br-option">process-max</span> can drastically improve performance by parallelizing operations. Be sure not to set <span class="br-option">process-max</span> so high that it affects normal database operations.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure the spool path and asynchronous archiving
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
archive-async=y<br/>
log-level-file=detail<br/>
repo1-host=repository<br/>
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
repo1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
repo1-host-type=tls<br/>
spool-path=/var/spool/pgbackrest<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=demo<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key<br/>
<br/>
[global:archive-get]<br/>
process-max=2<br/>
<br/>
[global:archive-push]<br/>
process-max=2
</div></div></div><div class="config"><div class="config-title">
<span class="host">pg-standby</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure the spool path and asynchronous archiving
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
recovery-option=primary_conninfo=host=172.17.0.6 port=5432 user=replicator<br/>
<br/>
[global]<br/>
archive-async=y<br/>
log-level-file=detail<br/>
repo1-host=repository<br/>
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
repo1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
repo1-host-type=tls<br/>
spool-path=/var/spool/pgbackrest<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=demo<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key<br/>
<br/>
[global:archive-get]<br/>
process-max=2<br/>
<br/>
[global:archive-push]<br/>
process-max=2
</div></div></div><div class="admonition"><div class="note">
NOTE:
</div><div class="note-text">
<span class="br-option">process-max</span> is configured using command sections so that the option is not used by backup and restore. This also allows different values for <span class="cmd">archive-push</span> and <span class="cmd">archive-get</span>.
</div></div><div class="section-body-text">
For demonstration purposes streaming replication will be broken to force <span class="postgres">PostgreSQL</span> to get WAL using the <span class="pg-option">restore_command</span>.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Break streaming replication by changing the replication password
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c "alter user replicator password 'bogus'"</pre>
<pre class="execute-body-output">ALTER ROLE</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Restart standby to break connection
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl restart postgresql-13.service</pre>
</div></div><div class="section2"><a id="async-archiving/async-archive-push"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Archive Push
</div></div><div class="section-body"><div class="section-body-text">
The asynchronous <span class="cmd">archive-push</span> command offloads WAL archiving to a separate process (or processes) to improve throughput. It works by <q>looking ahead</q> to see which WAL segments are ready to be archived beyond the request that <span class="postgres">PostgreSQL</span> is currently making via the <span class="id">archive_command</span>. WAL segments are transferred to the archive directly from the <span class="path">pg_xlog</span>/<span class="path">pg_wal</span> directory and success is only returned by the <span class="id">archive_command</span> when the WAL segment has been safely stored in the archive.
</div><div class="section-body-text">
The spool path holds the current status of WAL archiving. Status files written into the spool directory are typically zero length and should consume a minimal amount of space (a few MB at most) and very little IO. All the information in this directory can be recreated so it is not necessary to preserve the spool directory if the cluster is moved to new hardware.
</div><div class="admonition"><div class="important">
IMPORTANT:
</div><div class="important-text">
In the original implementation of asynchronous archiving, WAL segments were copied to the spool directory before compression and transfer. The new implementation copies WAL directly from the <span class="path">pg_xlog</span> directory. If asynchronous archiving was utilized in <span class="host">v1.12</span> or prior, read the <span class="host">v1.13</span> release notes carefully before upgrading.
</div></div><div class="section-body-text">
The <span class="file">[stanza]-archive-push-async.log</span> file can be used to monitor the activity of the asynchronous process. A good way to test this is to quickly push a number of WAL segments.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Test parallel asynchronous archiving
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c " \
       select pg_create_restore_point('test async push'); select pg_switch_wal(); \
       select pg_create_restore_point('test async push'); select pg_switch_wal(); \
       select pg_create_restore_point('test async push'); select pg_switch_wal(); \
       select pg_create_restore_point('test async push'); select pg_switch_wal(); \
       select pg_create_restore_point('test async push'); select pg_switch_wal();"</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --log-level-console=info check</pre>
<pre class="execute-body-output">P00   INFO: check command begin 2.55.0: --exec-id=5511-cb21831a --log-level-console=info --log-level-file=detail --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --stanza=demo
P00   INFO: check repo1 configuration (primary)
P00   INFO: check repo1 archive for WAL (primary)</pre>
<pre class="execute-body-output-highlight">P00   INFO: WAL segment 00000007000000000000002D successfully archived to '/var/lib/pgbackrest/archive/demo/13-1/0000000700000000/00000007000000000000002D-4bd363f7546edd3efde7b1ba090b69f1040593dc.gz' on repo1</pre>
<pre class="execute-body-output">P00   INFO: check command end: completed successfully</pre>
</div></div><div class="section-body-text">
Now the log file will contain parallel, asynchronous activity.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Check results in the log
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres cat /var/log/pgbackrest/demo-archive-push-async.log</pre>
<pre class="execute-body-output">-------------------PROCESS START-------------------
P00   INFO: archive-push:async command begin 2.55.0: [/var/lib/pgsql/13/data/pg_wal] --archive-async --exec-id=5481-f44d1eeb --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --process-max=2 --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --spool-path=/var/spool/pgbackrest --stanza=demo</pre>
<pre class="execute-body-output-highlight">P00   INFO: push 1 WAL file(s) to archive: 000000070000000000000028
P01 DETAIL: pushed WAL file '000000070000000000000028' to the archive</pre>
<pre class="execute-body-output">P00 DETAIL: statistics: {"socket.client":{"total":1},"socket.session":{"total":1},"tls.client":{"total":1},"tls.session":{"total":1}}
P00   INFO: archive-push:async command end: completed successfully

-------------------PROCESS START-------------------
P00   INFO: archive-push:async command begin 2.55.0: [/var/lib/pgsql/13/data/pg_wal] --archive-async --exec-id=5513-df50761d --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --process-max=2 --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --spool-path=/var/spool/pgbackrest --stanza=demo</pre>
<pre class="execute-body-output-highlight">P00   INFO: push 5 WAL file(s) to archive: 000000070000000000000029...00000007000000000000002D
P02 DETAIL: pushed WAL file '00000007000000000000002A' to the archive
P01 DETAIL: pushed WAL file '000000070000000000000029' to the archive
P02 DETAIL: pushed WAL file '00000007000000000000002B' to the archive
P01 DETAIL: pushed WAL file '00000007000000000000002C' to the archive
P02 DETAIL: pushed WAL file '00000007000000000000002D' to the archive</pre>
<pre class="execute-body-output">P00 DETAIL: statistics: {"socket.client":{"total":1},"socket.session":{"total":1},"tls.client":{"total":1},"tls.session":{"total":1}}
P00   INFO: archive-push:async command end: completed successfully</pre>
</div></div></div></div><div class="section2"><a id="async-archiving/async-archive-get"></a><div class="section2-header"><div class="section2-number"></div><div class="section2-title">
Archive Get
</div></div><div class="section-body"><div class="section-body-text">
The asynchronous <span class="cmd">archive-get</span> command maintains a local queue of WAL to improve throughput. If a WAL segment is not found in the queue it is fetched from the repository along with enough consecutive WAL to fill the queue. The maximum size of the queue is defined by <span class="br-option">archive-get-queue-max</span>. Whenever the queue is less than half full more WAL will be fetched to fill it.
</div><div class="section-body-text">
Asynchronous operation is most useful in environments that generate a lot of WAL or have a high latency connection to the repository storage (i.e., <span class="host">S3</span> or other object stores). In the case of a high latency connection it may be a good idea to increase <span class="br-option">process-max</span>.
</div><div class="section-body-text">
The <span class="file">[stanza]-archive-get-async.log</span> file can be used to monitor the activity of the asynchronous process.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Check results in the log
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres cat /var/log/pgbackrest/demo-archive-get-async.log</pre>
<pre class="execute-body-output">-------------------PROCESS START-------------------
P00   INFO: archive-get:async command begin 2.55.0: [000000070000000000000024, 000000070000000000000025, 000000070000000000000026, 000000070000000000000027, 000000070000000000000028, 000000070000000000000029, 00000007000000000000002A, 00000007000000000000002B] --archive-async --exec-id=1711-e6e77f2e --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --process-max=2 --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --spool-path=/var/spool/pgbackrest --stanza=demo
P00   INFO: get 8 WAL file(s) from archive: 000000070000000000000024...00000007000000000000002B</pre>
<pre class="execute-body-output-highlight">P01 DETAIL: found 000000070000000000000024 in the repo1: 13-1 archive
P02 DETAIL: found 000000070000000000000025 in the repo1: 13-1 archive
P02 DETAIL: found 000000070000000000000027 in the repo1: 13-1 archive
P01 DETAIL: found 000000070000000000000026 in the repo1: 13-1 archive</pre>
<pre class="execute-body-output">P00 DETAIL: unable to find 000000070000000000000028 in the archive
P00 DETAIL: statistics: {"socket.client":{"total":1},"socket.session":{"total":1},"tls.client":{"total":1},"tls.session":{"total":1}}
       [filtered 31 lines of output]
P00   INFO: archive-get:async command begin 2.55.0: [000000070000000000000028, 000000070000000000000029, 00000007000000000000002A, 00000007000000000000002B, 00000007000000000000002C, 00000007000000000000002D, 00000007000000000000002E, 00000007000000000000002F] --archive-async --exec-id=1762-650b709b --log-level-console=off --log-level-file=detail --log-level-stderr=off --no-log-timestamp --pg1-path=/var/lib/pgsql/13/data --process-max=2 --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --spool-path=/var/spool/pgbackrest --stanza=demo
P00   INFO: get 8 WAL file(s) from archive: 000000070000000000000028...00000007000000000000002F</pre>
<pre class="execute-body-output-highlight">P02 DETAIL: found 000000070000000000000029 in the repo1: 13-1 archive
P01 DETAIL: found 000000070000000000000028 in the repo1: 13-1 archive
P02 DETAIL: found 00000007000000000000002A in the repo1: 13-1 archive
P01 DETAIL: found 00000007000000000000002B in the repo1: 13-1 archive
P02 DETAIL: found 00000007000000000000002C in the repo1: 13-1 archive
P01 DETAIL: found 00000007000000000000002D in the repo1: 13-1 archive</pre>
<pre class="execute-body-output">P00 DETAIL: unable to find 00000007000000000000002E in the archive
P00 DETAIL: statistics: {"socket.client":{"total":1},"socket.session":{"total":1},"tls.client":{"total":1},"tls.session":{"total":1}}
       [filtered 7 lines of output]</pre>
</div></div></div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Fix streaming replication by changing the replication password
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres psql -c "alter user replicator password 'jw8s0F4'"</pre>
<pre class="execute-body-output">ALTER ROLE</pre>
</div></div></div></div><div class="section1"><a id="standby-backup"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Backup from a Standby
</div></div><div class="section-body"><div class="section-body-text">
<span class="backrest">pgBackRest</span> can perform backups on a standby instead of the primary. Standby backups require the <span class="host">pg-standby</span> host to be configured and the <span class="br-option">backup-standby</span> option enabled. If more than one standby is configured then the first running standby found will be used for the backup.
</div><div class="config"><div class="config-title">
<span class="host">repository</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Configure <span class="br-option">pg2-host</span>/<span class="br-option">pg2-host-user</span> and <span class="br-option">pg2-path</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-host=pg-primary<br/>
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg1-host-type=tls<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
pg2-host=pg-standby<br/>
pg2-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg2-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg2-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg2-host-type=tls<br/>
pg2-path=/var/lib/pgsql/13/data<br/>
<br/>
[demo-alt]<br/>
pg1-host=pg-alt<br/>
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg1-host-type=tls<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
backup-standby=y<br/>
process-max=3<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-full=2<br/>
start-fast=y<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=*<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key
</div></div></div><div class="section-body-text">
Both the primary and standby databases are required to perform the backup, though the vast majority of the files will be copied from the standby to reduce load on the primary. The database hosts can be configured in any order. <span class="backrest">pgBackRest</span> will automatically determine which is the primary and which is the standby.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Backup the demo cluster from <span class="host">pg2</span>
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest pgbackrest --stanza=demo --log-level-console=detail backup</pre>
<pre class="execute-body-output">       [filtered 2 lines of output]
P00   INFO: execute non-exclusive backup start: backup begins after the requested immediate checkpoint completes
P00   INFO: backup start archive = 00000007000000000000002F, lsn = 0/2F000028</pre>
<pre class="execute-body-output-highlight">P00   INFO: wait for replay on the standby to reach 0/2F000028
P00   INFO: replay on the standby reached 0/2F000028</pre>
<pre class="execute-body-output">P00   INFO: check archive for prior segment 00000007000000000000002E</pre>
<pre class="execute-body-output-highlight">P01 DETAIL: backup file pg-primary:/var/lib/pgsql/13/data/log/postgresql.log (11.2KB, 0.48%) checksum 0ab0ed392cd1eb096a240e6603b1acdcb8ca54e1
P01 DETAIL: backup file pg-primary:/var/lib/pgsql/13/data/global/pg_control (8KB, 0.83%) checksum 7f9eedf2565b2097757a3f122e168488e41ea3fb
P01 DETAIL: backup file pg-primary:/var/lib/pgsql/13/data/pg_hba.conf (4.5KB, 1.02%) checksum 65e54ae24bda87b2542351cb16a7fecc7e5aceeb</pre>
<pre class="execute-body-output">P01 DETAIL: match file from prior backup pg-primary:/var/lib/pgsql/13/data/current_logfiles (26B, 1.03%) checksum 78a9f5c10960f0d91fcd313937469824861795a2
P01 DETAIL: match file from prior backup pg-primary:/var/lib/pgsql/13/data/pg_logical/replorigin_checkpoint (8B, 1.03%) checksum 347fc8f2df71bd4436e38bd1516ccd7ea0d46532
       [filtered 1243 lines of output]</pre>
</div></div><div class="section-body-text">
This incremental backup shows that most of the files are copied from the <span class="host">pg-standby</span> host and only a few are copied from the <span class="host">pg-primary</span> host.
</div><div class="section-body-text">
<span class="backrest">pgBackRest</span> creates a standby backup that is identical to a backup performed on the primary. It does this by starting/stopping the backup on the <span class="host">pg-primary</span> host, copying only files that are replicated from the <span class="host">pg-standby</span> host, then copying the remaining few files from the <span class="host">pg-primary</span> host. This means that logs and statistics from the primary database will be included in the backup.
</div></div></div><div class="section1"><a id="upgrade-stanza"></a><div class="section1-header"><div class="section1-number"></div><div class="section1-title">
Upgrading <span class="postgres">PostgreSQL</span>
</div></div><div class="section-body"><div class="section-body-text">
Immediately after upgrading <span class="postgres">PostgreSQL</span> to a newer major version, the <span class="br-option">pg-path</span> for all <span class="backrest">pgBackRest</span> configurations must be set to the new database location and the <span class="cmd">stanza-upgrade</span> command run. If there is more than one repository configured on the host, the stanza will be upgraded on each. If the database is offline use the <span class="br-option">--no-online</span> option.
</div><div class="section-body-text">
The following instructions are not meant to be a comprehensive guide for upgrading <span class="postgres">PostgreSQL</span>, rather they outline the general process for upgrading a primary and standby with the intent of demonstrating the steps required to reconfigure <span class="backrest">pgBackRest</span>. It is recommended that a backup be taken prior to upgrading.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Stop old cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl stop postgresql-13.service</pre>
</div></div><div class="section-body-text">
Stop the old cluster on the standby since it will be restored from the newly upgraded cluster.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Stop old cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl stop postgresql-13.service</pre>
</div></div><div class="section-body-text">
Create the new cluster and perform upgrade.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Create new cluster and perform the upgrade
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres /usr/pgsql-14/bin/initdb \
       -D /var/lib/pgsql/14/data -k -A peer</pre>
<pre class="execute-body-cmd">sudo -u postgres sh -c 'cd /var/lib/pgsql &amp;&amp; \
       /usr/pgsql-14/bin/pg_upgrade \
       --old-bindir=/usr/pgsql-13/bin \
       --new-bindir=/usr/pgsql-14/bin \
       --old-datadir=/var/lib/pgsql/13/data \
       --new-datadir=/var/lib/pgsql/14/data \
       --old-options=" -c config_file=/var/lib/pgsql/13/data/postgresql.conf" \
       --new-options=" -c config_file=/var/lib/pgsql/14/data/postgresql.conf"'</pre>
<pre class="execute-body-output">       [filtered 68 lines of output]
Checking for extension updates                              ok
</pre>
<pre class="execute-body-output-highlight">Upgrade Complete</pre>
<pre class="execute-body-output">----------------
Optimizer statistics are not transferred by pg_upgrade.
       [filtered 4 lines of output]</pre>
</div></div><div class="section-body-text">
Configure the new cluster settings and port.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/var/lib/pgsql/14/data/postgresql.conf</span> <b>&#x21d2;</b> Configure <span class="postgres">PostgreSQL</span>
</div><div class="config-body"><div class="config-body-output">
archive_command = 'pgbackrest --stanza=demo archive-push %p'<br/>
archive_mode = on<br/>
log_filename = 'postgresql.log'<br/>
max_wal_senders = 3<br/>
wal_level = replica
</div></div></div><div class="section-body-text">
Update the <span class="backrest">pgBackRest</span> configuration on all systems to point to the new cluster.
</div><div class="config"><div class="config-title">
<span class="host">pg-primary</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Upgrade the <span class="br-option">pg1-path</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/14/data<br/>
<br/>
[global]<br/>
archive-async=y<br/>
log-level-file=detail<br/>
repo1-host=repository<br/>
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
repo1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
repo1-host-type=tls<br/>
spool-path=/var/spool/pgbackrest<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=demo<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key<br/>
<br/>
[global:archive-get]<br/>
process-max=2<br/>
<br/>
[global:archive-push]<br/>
process-max=2
</div></div></div><div class="config"><div class="config-title">
<span class="host">pg-standby</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Upgrade the <span class="br-option">pg-path</span>
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-path=/var/lib/pgsql/14/data<br/>
recovery-option=primary_conninfo=host=172.17.0.6 port=5432 user=replicator<br/>
<br/>
[global]<br/>
archive-async=y<br/>
log-level-file=detail<br/>
repo1-host=repository<br/>
repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
repo1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
repo1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
repo1-host-type=tls<br/>
spool-path=/var/spool/pgbackrest<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=demo<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key<br/>
<br/>
[global:archive-get]<br/>
process-max=2<br/>
<br/>
[global:archive-push]<br/>
process-max=2
</div></div></div><div class="config"><div class="config-title">
<span class="host">repository</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Upgrade <span class="br-option">pg1-path</span> and <span class="br-option">pg2-path</span>, disable backup from standby
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-host=pg-primary<br/>
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg1-host-type=tls<br/>
pg1-path=/var/lib/pgsql/14/data<br/>
pg2-host=pg-standby<br/>
pg2-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg2-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg2-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg2-host-type=tls<br/>
pg2-path=/var/lib/pgsql/14/data<br/>
<br/>
[demo-alt]<br/>
pg1-host=pg-alt<br/>
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg1-host-type=tls<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
backup-standby=n<br/>
process-max=3<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-full=2<br/>
start-fast=y<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=*<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key
</div></div></div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Copy hba configuration
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo cp /var/lib/pgsql/13/data/pg_hba.conf \
       /var/lib/pgsql/14/data/pg_hba.conf</pre>
</div></div><div class="section-body-text">
Before starting the new cluster, the <span class="cmd">stanza-upgrade</span> command must be run.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Upgrade the stanza
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --no-online \
       --log-level-console=info stanza-upgrade</pre>
<pre class="execute-body-output">P00   INFO: stanza-upgrade command begin 2.55.0: --exec-id=6025-fcfa8929 --log-level-console=info --log-level-file=detail --no-log-timestamp --no-online --pg1-path=/var/lib/pgsql/14/data --repo1-host=repository --repo1-host-ca-file=/etc/pgbackrest/cert/ca.crt --repo1-host-cert-file=/etc/pgbackrest/cert/client.crt --repo1-host-key-file=/etc/pgbackrest/cert/client.key --repo1-host-type=tls --stanza=demo
P00   INFO: stanza-upgrade for stanza 'demo' on repo1</pre>
<pre class="execute-body-output-highlight">P00   INFO: stanza-upgrade command end: completed successfully</pre>
</div></div><div class="section-body-text">
Start the new cluster and confirm it is successfully installed.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Start new cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl start postgresql-14.service</pre>
</div></div><div class="section-body-text">
Test configuration using the <span class="cmd">check</span> command.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Check configuration
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl status postgresql-14.service</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo check</pre>
</div></div><div class="section-body-text">
Remove the old cluster.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-primary</span> <b>&#x21d2;</b> Remove old cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo rm -rf /var/lib/pgsql/13/data</pre>
</div></div><div class="section-body-text">
Install the new <span class="postgres">PostgreSQL</span> binaries on the standby and create the cluster.
</div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Remove old cluster and create the new cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo rm -rf /var/lib/pgsql/13/data</pre>
<pre class="execute-body-cmd">sudo -u postgres mkdir -p -m 700 /usr/pgsql-14/bin</pre>
</div></div><div class="section-body-text">
Run the <span class="cmd">check</span> on the repository host. The warning regarding the standby being down is expected since the standby cluster is down. Running this command demonstrates that the repository server is aware of the standby and is configured properly for the primary server.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Check configuration
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest pgbackrest --stanza=demo check</pre>
<pre class="execute-body-output">P00   WARN: unable to check pg2: [DbConnectError] raised from remote-0 tls protocol on 'pg-standby': unable to connect to 'dbname='postgres' port=5432': could not connect to server: No such file or directory
            	Is the server running locally and accepting
            	connections on Unix domain socket "/run/postgresql/.s.PGSQL.5432"?</pre>
</div></div><div class="section-body-text">
Run a full backup on the new cluster and then restore the standby from the backup. The backup type will automatically be changed to <span class="id">full</span> if <span class="id">incr</span> or <span class="id">diff</span> is requested.
</div><div class="execute"><div class="execute-title">
<span class="host">repository</span> <b>&#x21d2;</b> Run a full backup
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u pgbackrest pgbackrest --stanza=demo --type=full backup</pre>
</div></div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Restore the demo standby cluster
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo --type=standby restore</pre>
</div></div><div class="config"><div class="config-title">
<span class="host">pg-standby</span>:<span class="file">/var/lib/pgsql/14/data/postgresql.conf</span> <b>&#x21d2;</b> Configure <span class="postgres">PostgreSQL</span>
</div><div class="config-body"><div class="config-body-output">
hot_standby = on
</div></div></div><div class="execute"><div class="execute-title">
<span class="host">pg-standby</span> <b>&#x21d2;</b> Start <span class="postgres">PostgreSQL</span> and check the <span class="backrest">pgBackRest</span> configuration
</div><div class="execute-body">
<pre class="execute-body-cmd">sudo systemctl start postgresql-14.service</pre>
<pre class="execute-body-cmd">sudo -u postgres pgbackrest --stanza=demo check</pre>
</div></div><div class="section-body-text">
Backup from standby can be enabled now that the standby is restored.
</div><div class="config"><div class="config-title">
<span class="host">repository</span>:<span class="file">/etc/pgbackrest/pgbackrest.conf</span> <b>&#x21d2;</b> Reenable backup from standby
</div><div class="config-body"><div class="config-body-output">
[demo]<br/>
pg1-host=pg-primary<br/>
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg1-host-type=tls<br/>
pg1-path=/var/lib/pgsql/14/data<br/>
pg2-host=pg-standby<br/>
pg2-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg2-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg2-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg2-host-type=tls<br/>
pg2-path=/var/lib/pgsql/14/data<br/>
<br/>
[demo-alt]<br/>
pg1-host=pg-alt<br/>
pg1-host-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
pg1-host-cert-file=/etc/pgbackrest/cert/client.crt<br/>
pg1-host-key-file=/etc/pgbackrest/cert/client.key<br/>
pg1-host-type=tls<br/>
pg1-path=/var/lib/pgsql/13/data<br/>
<br/>
[global]<br/>
backup-standby=y<br/>
process-max=3<br/>
repo1-path=/var/lib/pgbackrest<br/>
repo1-retention-full=2<br/>
start-fast=y<br/>
tls-server-address=*<br/>
tls-server-auth=pgbackrest-client=*<br/>
tls-server-ca-file=/etc/pgbackrest/cert/ca.crt<br/>
tls-server-cert-file=/etc/pgbackrest/cert/server.crt<br/>
tls-server-key-file=/etc/pgbackrest/cert/server.key
</div></div></div></div></div></div><div class="page-footer">
Copyright &copy; 2015-2025, The PostgreSQL Global Development Group, <a href="https://github.com/pgbackrest/pgbackrest/blob/main/LICENSE">MIT License</a>. Updated April 21, 2025
</div></body></html>