PGHoard PostgreSQL Backup and Restore for Object Storage

PGHoard's PostgreSQL Backup Boundary

PGHoard addresses a specific infrastructure problem: keeping PostgreSQL base backups and write-ahead log files outside the database host so that the database can be recovered after local disk or host failure. Its intended users are PostgreSQL administrators, system administrators, and organizations that retain backups in cloud object stores rather than only on the server being protected. The project supports local filesystems as well as AWS S3, Google Cloud, OpenStack Swift, Azure, and Ceph.

A PostgreSQL base backup alone cannot reproduce every change made after it was taken. PGHoard therefore combines periodic base backups with a continuing WAL archive. During recovery, PostgreSQL can use the base backup and replay WAL through a selected recovery point. The README identifies this as point-in-time recovery, or PITR.

PGHoard does not act as a substitute for PostgreSQL itself. It relies on PostgreSQL facilities and utilities, including pg_receivexlog, archive_command, walreceiver, and pg_basebackup. The database server, its replication or archive settings, the PGHoard configuration, and the backup destination all have to form a working arrangement. This is important for adoption because installing the Python package alone does not create a protected database.

WAL Capture Modes and Base Backup Flow

PGHoard supports several operating models. In the basic model, the daemon connects with pg_receivexlog and receives WAL files as PostgreSQL writes them. A second model uses pghoard_postgres_command as a PostgreSQL archive_command. A third mode, described as experimental, lets PGHoard use PostgreSQL's native replication protocol through walreceiver. The documentation does not present those three paths as equivalent in maturity, so an operator should select according to the database deployment and validate the exact behavior in that environment.

For base backups, PGHoard runs pg_basebackup against the source database. The resulting data is compressed before storage. PGHoard also captures transaction log metadata through psycopg2, while requests supports the project's internal client-server architecture. Those dependencies explain why this is a daemon rather than a single storage upload script.

Compression is configurable among Snappy, Zstandard, and LZMA. Snappy is the default. The README says Zstandard defaults to level 3 and LZMA to level 0, but it also advises testing algorithms for the workload rather than treating those defaults as universal. Compression choice affects upload volume, CPU use, and restore download work. PGHoard additionally documents parallel compression and encryption, plus WAL prefetching during restore.

Installing PGHoard from a Checkout

The repository is built around Hatchling and can be installed from a Git checkout. The Makefile's development dependency target runs two pip commands. The first installs the project, and the second installs its development extras.

From the repository root, install the package and development dependencies:

make dev-deps

The target is intended for development and testing because its second command requests the dev extra, which includes pytest, mypy, pylint, formatting tools, mock libraries, and related packages. The pyproject.toml declares Python 3.10, 3.11, and 3.12 as classifiers, while the README says the daemon is developed with Python 3.10 and above. The package metadata also states requires-python = ">=3.8", so operators should treat the README's development target as the more relevant compatibility guidance.

PGHoard also needs PostgreSQL-side tools and modules appropriate to the chosen storage backend. The README names psycopg2, requests, and optional packages for Azure, AWS S3, Google Cloud, Swift, encryption, Snappy, Zstandard, systemd, and SFTP. It does not provide a complete production installation tutorial, service startup command, or a minimal daemon configuration. The repository does include pghoard.json and pghoard-local-minimal.json, but their contents and the resulting command line are not documented in the supplied files, so a first daemon invocation cannot be reproduced reliably from the available instructions.

First Backup Setup: Configuration Before Execution

A real first use starts with defining how PGHoard reaches PostgreSQL and where it stores backup artifacts. The documentation identifies pghoard.json and pghoard-local-minimal.json as repository files, and it describes local storage plus several object-storage backends. Administrators should consult those files directly rather than treating them as a verified ready-to-run tutorial.

The setup must also choose an archive model. A deployment can use pg_receivexlog from a separate backup machine, configure pghoard_postgres_command as archive_command, or investigate the experimental walreceiver mode. The choice affects PostgreSQL configuration, network permissions, and how WAL enters the archive. After selecting it, an administrator needs to provide the database connection details, archive credentials, retention behavior, compression choice, and monitoring locations required by the daemon.

The first operational check should look for a base backup and subsequent WAL files in the selected destination. The README also documents statistics files and alert files for monitoring systems. Those files are useful indicators that the daemon has reported state. Do not infer that a successful package installation means the WAL stream is complete. PGHoard provides an archive sync tool for detecting holes and attempting fixes, while archive cleanup removes obsolete files, so archive continuity requires separate verification.

Recovery, Encryption, and Object-Storage Failure Handling

PGHoard restores directly from object storage and supports compressed and encrypted backup data. Its encryption model is more specific than simply applying a password to an archive. Each file is encrypted and authenticated with file-specific keys. Those keys are included in the backup after encryption with a master RSA private/public key pair. Operators therefore need to account for master-key custody and the ability to retrieve the material needed during recovery. A backup service cannot recover encrypted files without the corresponding key material.

The project also handles some operational failure cases. It retries transfers across temporary object-storage connectivity problems. It checks WAL file headers before upload and after download, which the README says allows recycled PostgreSQL files to be ignored. Automatic history cleanup removes backups and related WAL files older than a configured number of days. These are useful safeguards, but the documentation does not specify every retention boundary or retry policy.

PGHoard can initialize a standby from object-storage backups and configure it as a replicating hot standby. That covers a recovery path beyond restoring files onto an ordinary server. The README does not document a complete PostgreSQL recovery walkthrough, required recovery settings, or a rollback procedure. Those details must be established from the project documentation and the target PostgreSQL version before relying on the service for disaster recovery.

PGHoard Limitations and the borg Alternative

PGHoard has several boundaries. It requires a PostgreSQL deployment that can supply base backups and WAL through one of its supported mechanisms. It depends on Python modules and PostgreSQL utilities, so a minimal environment will need more than the core Python daemon. The walreceiver path is explicitly experimental. Compression is a trade-off between speed and archive size, and the README does not prescribe one algorithm for every workload.

For an evaluation, compare PGHoard's PostgreSQL-specific base-backup, WAL, PITR, and object-storage workflows against the organization's recovery objectives.

Maintenance, Compatibility, and Apache-2.0 Costs

The repository is not archived, and its last push was on 2026-10-13. Recent releases include 2.8.0 on 2026-07-30, 2.7.2 on 2026-07-25, and 2.7.1 on 2026-06-17. Those records indicate recent project activity, but they do not eliminate upgrade work. PGHoard supports PostgreSQL versions 9.3 and above, while the README says it is tested and actively developed with version 13 and above. It has been developed and tested on modern Linux x86-64 systems. A PostgreSQL major-version change, Python dependency change, storage-library change, or encryption configuration change can therefore affect validation effort.

The project uses Apache-2.0. That license permits use and modification under its terms, including the patent and redistribution conditions stated in the LICENSE file. This review does not interpret those legal terms or provide legal advice. Operators should still review the repository LICENSE and any bundled dependency licenses when distributing modified packages or integrating PGHoard into a commercial environment. The practical upgrade cost includes reviewing release changes, rebuilding the service, retesting restore and PITR, and checking storage compatibility.

Editorial conclusion

PGHoard is appropriate for PostgreSQL administrators who need base backups, continuous WAL capture, object-storage recovery, or PITR and can operate its Python service and PostgreSQL dependencies. It is less suitable for environments without a reachable PostgreSQL instance, compatible client tools, and storage credentials. Verify Python and PostgreSQL compatibility, the selected archive mechanism, object-storage access, encryption-key custody, and a complete restore before adopting it for production backups.

Frequently asked questions

Official sources

1. Aiven-Open/pghoard on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases