Learn pgBackRest - Installation & Basic Configuration

#Introduction

After understanding the architecture in episode 2, it's time for the first real action: installing pgBackRest and writing your first configuration. In episode 3 we cover two installation paths — the distribution package for speed and building from source for full control — then prepare the repository directory and write a correct /etc/pgbackrest.conf.

The "package or build yourself" decision isn't just about convenience. In production, the package from the official repo (PGDG) is the sanest choice because it's already tested against PostgreSQL and has its dependencies handled. Building from source is useful when you want the newest features not yet in a package, or to customize the build. We'll cover both.

#Installation Prerequisites

Make sure PostgreSQL is installed (episode 0) and the postgres user exists. Check the build dependencies if you choose the source path:

gcc --version
make --version

Building from source requires a C compiler and make. Distribution packages usually don't need these because the binary is already provided.

#Installing via Distribution Package

The fastest and most recommended approach. On Debian/Ubuntu with the PGDG repo:

sudo apt update
sudo apt install -y pgbackrest

On RHEL/Fedora/Rocky:

sudo dnf install -y pgbackrest

Verify the result:

pgbackrest version

The output must show pgbackrest 2.59.0. The package also provides an empty config file at /etc/pgbackrest.conf and a log directory at /var/log/pgbackrest/.

#Building from Source

If the distro package doesn't yet have 2.59.0, or you need full build control:

wget https://github.com/pgbackrest/pgbackrest/archive/refs/tags/release/2.59.0.tar.gz
tar -xzf 2.59.0.tar.gz
cd pgbackrest-release-2.59.0/src
./configure
make -s

The result is a binary at src/pgbackrest. Install it to the standard location:

sudo cp pgbackrest /usr/bin/pgbackrest
sudo chmod 755 /usr/bin/pgbackrest
pgbackrest version

#Preparing the Directories and User

pgBackRest runs as the postgres user for local backups (so it can read PGDATA and write WAL). Every directory it touches must be owned by that user:

sudo mkdir -p /var/lib/pgbackrest
sudo chown -R postgres:postgres /var/lib/pgbackrest
sudo mkdir -p /var/log/pgbackrest
sudo chown -R postgres:postgres /var/log/pgbackrest

This permission pattern is important: archive_command is executed by the PostgreSQL process (the postgres user), so the postgres user must be able to write to the repository. In episode 15 we'll see how often permission denied on archive-push has its root in this small step.

#Writing the Basic Configuration

All pgBackRest configuration lives in /etc/pgbackrest.conf in INI format. The [global] section applies to all stanzas; the [stanza-name] section is specific to one cluster. For a local cluster with PGDATA at /var/lib/postgresql/16/main:

[global]
repo1-path = /var/lib/pgbackrest
repo1-retention-full = 2
log-level-file = info
process-max = 2
 
[main]
pg1-path = /var/lib/postgresql/16/main
pg1-port = 5432
pg1-user = postgres

Explanation of each option:

• repo1-path — repository location. The value must match the directory we created.
• repo1-retention-full — how many full backups to keep (retention details in episode 5).
• log-level-file — the log level written to /var/log/pgbackrest/; raise it to debug when troubleshooting (episode 15).
• process-max — the number of parallel processes for backup/restore (episode 7).
• pg1-path — the cluster's PGDATA location. Required and must be exact.
• pg1-user — the user running PostgreSQL; defaults to postgres.
• pg1-port — the PostgreSQL port; only needed if it isn't 5432.

Note: because the database and repository are on the same host, we don't write pg1-host or repo1-host. Those options only appear for remote mode (episode 12).

#Verifying the Configuration

pgBackRest provides a quick way to make sure the config is valid — it reads the config and displays the effective values:

pgbackrest --stanza=main config

The config command prints all options that apply to the main stanza, including those taken from defaults. This is a very useful debugging tool: you see the final values of repo1-path and pg1-path directly, without guessing.

If an option is misspelled, pgBackRest refuses to run the command with a clear error message. At this point the basic installation and configuration are done — but no stanza has actually been created yet. That's the work of episode 4.

#Conclusion

Key takeaways:

• Install via the distro package for production; build from source for control/newest features.
• The built binary comes from src/pgbackrest — install it to /usr/bin/pgbackrest.
• The /var/lib/pgbackrest and /var/log/pgbackrest directories must be owned by the postgres user.
• Config /etc/pgbackrest.conf = [global] section (repo1-path, log-level, process-max) + [stanza] section (pg1-path, pg1-user).
• pgbackrest --stanza=main config to verify the effective values of all options.

In the next episode we'll bring a stanza to life for the first time: pgbackrest stanza-create, validate the entire chain (database, repository, archive) with pgbackrest check, then run your first full backup and read the results via pgbackrest info. This is the first moment your repository holds real data!