pg_back dumps every PostgreSQL database in custom format, not plain SQL

The problem starts with pg_dumpall only producing plain SQL

pg_back exists because of a specific limitation in the standard tooling. The stated goal is to dump all or some databases with globals at once in the format you want, because a simple call to pg_dumpall only dumps databases in the plain SQL format.

Behind that wrapper, the work is split between the two PostgreSQL programs. pg_dumpall is used to dump roles and tablespaces definitions, and pg_dump is used to dump all or each selected database to a separate file in the custom format. The tool also extracts database level ACL and configuration that is not dumped by pg_dump older than 11, and it dumps all configuration options of the PostgreSQL instance.

That last point is the one operators tend to miss. A dump of the databases is not a dump of the instance. Roles, tablespaces, per-database grants, per-database settings and the instance-wide configuration are separate things in PostgreSQL, and a restore that only replays the data files leaves you with a cluster that does not match the one you backed up. pg_back treats those as part of the same run, which is the whole reason to use it rather than a shell script that loops over pg_dump.

The tool is written in Go, with the module path github.com/orgrim/pg_back, and it needs pg_dump and pg_dumpall present on the machine since it calls them rather than implementing the dump format itself.

Installation is a binary, a go install, or a throwaway container

There are three routes to a working pg_back, and all of them are short. A compiled binary is published on the GitHub releases page, and the documentation is explicit that the binary only needs pg_dump and pg_dumpall, nothing else from a PostgreSQL server install.

Building from source through the Go toolchain is one line:

go install github.com/orgrim/pg_back@latest

The Makefile offers the same thing in a more granular way, with an install target that runs go install, a test target that produces a coverage profile, and coverage targets that render it as a function summary or as HTML. The install target simply runs go install for the package.

The documentation says to use make to build and install from source and that you need go 1.20 or above, while the module file itself declares go 1.26.0, so the released module expects a much newer toolchain than the prose suggests. If you plan to build rather than download, take the module directive as the requirement.

The third route avoids installing anything locally. The documentation offers a docker command that downloads, compiles and drops the binary in the current directory:

docker run -u $(id -u) --rm -v "$PWD":/go/bin golang:1.20 -v "$PWD/.cache":/.cache \
    go install github.com/orgrim/pg_back@latest

The container is the project Dockerfile, which builds with CGO disabled for a static binary and then copies it into an Alpine image with the postgresql-client package installed, since the tool needs the client programs at runtime. The entrypoint is the binary itself.

Per-database configuration uses ini sections, not command line flags

The configuration file is the interesting part of the design, because it allows different rules per database. It uses the ini format, with global options in an unspecified section at the top of the file and database specific options in a section named after the database. Per database options override global options, and the documentation is clear that the command line options override configuration options.

Only a configuration file can express per-database behaviour. Inside a database section you can list schemas or tables to exclude from or select in the dump, and for those the rules of the -t, -T, -n and -N options of pg_dump apply, along with its pattern rules. The repository ships a pg_back.conf file at the top level, referenced by name in the documentation, and the tool is invoked with -c and a configuration filename.

The database selection logic has a few sharp edges worth knowing. When no database names are given on the command line, all databases except templates are dumped. Templates can be included with --with-templates, and --without-templates forces their exclusion if the configuration file had included them. Databases can be excluded with --exclude-dbs, which takes a comma separated list, and if a database appears both on the command line and in the exclusion list, exclusion wins.

There is also a distinction between two job options that are easy to confuse. --jobs controls the number of concurrent pg_dump jobs, so databases can be dumped at the same time, while --parallel-backup-jobs controls the number of sessions pg_dump itself uses with the directory format.

Checksums, retention rules and hooks, and how they interact

Three operational features sit on top of the dumping itself, and one of them is a subtle interaction.

Checksums are optional and off unless you ask for them. When --checksum-algo is set to something other than none, a checksum of all output files is computed into a separate file. The available algorithms are sha1, sha224, sha256, sha384 and sha512, and the output file uses the format required by the shaXsum tools, so it can be verified with their -c option.

Retention is expressed as two rules. --purge-older-than takes an age in days when no unit is given, and the accepted units are the ones understood by the Go time.ParseDuration function, so s for seconds, m for minutes, h for hours and so on. --purge-min-keep sets how many dump files to keep, with the special value all keeping everything and avoiding file removal completely.

The interaction is the part to get right. When both are used, the minimum number of dumps to keep is enforced before old dumps are removed, which prevents the situation where a short age interval deletes everything you have. That ordering is a safety feature, and it means you can set a tight age without risking an empty backup directory.

Hooks run a command before and after the dumps with --pre-backup-hook and --post-backup-hook. The commands are executed directly rather than through a shell, respecting single and double quoted values, and the post backup hook still runs when some other operation fails, which makes it usable as a failure notification.

Encryption with age, and uploading dumps to object storage

All the files produced by a run can be encrypted, and the tool uses age, described as an easy to use tool that does authenticated encryption of files. Encryption works with a passphrase or with a key pair.

For the passphrase route, the --encrypt option is combined with either the --cipher-pass option or the PGBK_CIPHER_PASS environment variable to supply the passphrase. The environment variable matters for scheduled runs, since a cron job that needs a passphrase on its command line exposes it in the process list.

Upload and download is a separate axis of the tool, and the destinations are named in the feature list: S3, GCS, Azure, B2, or a remote host over SFTP. The dependency list in the module file backs that up, with the AWS SDK, the Google Cloud storage client, the Azure blob storage SDK, the Backblaze blazer client for B2, and a pure Go SFTP package, plus a generic HTTP client for the remaining cases.

The combination of the two is the reason to use this tool rather than a hand-rolled script. A backup that is encrypted at rest, uploaded to a remote object store, checksummed and then purged on a retention rule is a pipeline, and pg_back expresses the whole pipeline in one command with one configuration file.

One feature is worth calling out separately because it changes the operational profile. The tool can dump from a hot standby by pausing replication replay, so the backup does not compete with the primary for resources on a replicated cluster.

Output paths, file permissions and timestamps you can rely on

Where the files land has its own rules. The default output directory is /var/backups/postgresql, and if that directory does not exist or has improper ownership for your user, the -b option gives the path to use instead. That path may contain the {dbname} keyword, which is replaced by the name of the database being dumped, so each database can be dumped into its own directory.

File permissions are locked down by default. Files are created with script file permissions, 0600, and the --backup-file-mode option changes that. Permissions on directories are deduced from the file mode, adding the x bit if necessary, which means a dump directory you create yourself does not need a separate chmod as long as the mode you chose is sensible.

Timestamps are the last detail, and they are the one most likely to confuse a restore. A run creates multiple files, with the date and time of their creation in the filename, which helps you find the point in time the data can be restored to, but all timestamps in a filename are potentially different. The --uniform-timestamp option changes this behaviour so that all files output by a run use the same date and time, taken from the time of the first dump of the run.

That option is what you want whenever a set of files has to be consistent with each other, for example when a data dump and a configuration dump have to be replayed as a pair. Left at the default, the filenames alone do not guarantee that they describe the same instant.

A custom licence, an old PostgreSQL baseline, and a quiet release cadence

The licence needs a look before you build a process around this. The repository carries a LICENSE file and GitHub cannot classify it, which means the terms are not MIT, not Apache-2.0 and not any of the licences the platform recognises automatically. The README text reproduced here does not set out what those terms are, so read the LICENSE file directly before using pg_back in a commercial or hosted context.

On the PostgreSQL side, the documented minimum version of pg_dump and pg_dumpall required to dump is 8.4, and the oldest tested server version of PostgreSQL is 8.2. Those are old baselines, which tells you the tool has been kept working across a very long span of PostgreSQL versions. The practical implication is the opposite direction: a modern server is not a risk for this tool, but a dump taken on a new server may not be restorable into an old one, which is a property of the dump format rather than of pg_back.

The release history is slower than the push history. The tags are v2.6.0 from 2025-07-27, v2.5.0 from 2024-09-07 and v2.4.0 from 2024-06-21, and the last push was on 2026-06-02. So the branch is receiving work that has not been cut into a tagged release, and a team that pins to the v2.6.0 binary is running a build that is roughly a year behind the source. The repository also has a CHANGELOG, a .goreleaser.yml for the release builds, a Dockerfile, a docker directory, a contrib directory and a testdata directory.

Editorial conclusion

Adopt pg_back if you run PostgreSQL yourself and need one command that dumps all databases in a restorable format, with per-database rules, checksums, retention and encryption handled for you. Do not adopt it if you want a managed, monitored backup product with a support contract, since this is a tool you schedule and configure yourself. Before you run it on a real instance, check three things: the version of pg_dump and pg_dumpall on the host, since the documented minimum is 8.4 and the oldest tested server is 8.2, the permissions on the output directory, because files default to mode 0600 and directories need the x bit, and the LICENSE file, since the repository carries a custom licence that GitHub cannot classify and its terms are not one of the standard ones.

Frequently asked questions

Official sources

1. Issues
2. orgrim/pg_back on GitHub
3. README
4. Releases