PG_BACKUPCLUSTER(1)

📦
version 293ubuntu1 · 8 versions
, in ubuntu stonking

💖 PG_BACKUPCLUSTER(1) 💖

okay bestie, this is pg_backupcluster — a Debian PostgreSQL infrastructure babe. she's a little front-end and she's about to make your whole backup situation iconic. pull up a chair 🫶

✨ NAME ✨

pg_backupcluster — a simple pg_basebackup and pg_dump front-end. that's it, that's the girl.

🌸 SYNOPSIS 🌸

pg_backupcluster [options] version cluster action

🦋 DESCRIPTION 🦋

so basically pg_backupcluster gives you the simplest possible interface for making PostgreSQL cluster backups, and she does it using pg_basebackup(1) and pg_dump(1). no cap. 💅

and because systemd integration needs to be easy too, there's an alternate syntax that also works:

pg_basebackup version-cluster action

literally both are fine, she just wants you to win. ✨

🎀 ACTIONS 🎀

  • createdirectory — makes /var/backups/postgresql and /var/backups/postgresql/version-cluster. this one's the one you run as root to set up the dirs backups need. all the other actions will also try to create the directories if they're missing, but bestie they can obviously only do that if they're running as root. after that step they switch over to the cluster owner. 🫡
  • basebackup — backup time, using pg_basebackup(1). the basebackup it spits out contains the WAL files you need to run recovery on startup. slay.
  • dump — backup via pg_dump(1). global objects (users, tablespaces) get dumped using pg_dumpall(1) --globals-only. individual databases get dumped into PostgreSQL's custom format.
  • expirebasebackups N — removes all but the last N basebackups. bye girl 👋
  • expiredumps N — removes all but the last N dumps.
  • deletebroken — removes all broken backups. the cleanup we love to see.
  • receivewal — launches pg_receivewal. WAL files are gzip-compressed in PG 10+.
  • compresswal — compresses WAL files in the archive.
  • archivecleanup — removes obsolete WAL files from the archive using pg_archivecleanup(1).
  • list — shows dumps, basebackups, and WAL, with size. the receipts. 🧾

✨ OPTIONS ✨

  • -c, --checkpoint=spread|fast — passed straight to pg_basebackup. default is spread.
  • -k, --keep-on-error — keeps the broken backup directory when there's an error. by default, backups get deleted on error. you can clean up broken backups later with the deletebroken action. 💀
  • -v, --verbose — verbose output, even when you're not running on a terminal. she's chatty and she owns it.
  • -Z level, --compress=level — passed to pg_dump, pg_basebackup and pg_receivewal. default is pg_dump's default compression, gzip for pg_basebackup, and 5 for pg_receivewal.

🌈 FILES 🌈

  • /var/backups/postgresql — default root directory for cluster backup directories.
  • /var/backups/postgresql/version-cluster — default directory for cluster backups.
  • /var/backups/postgresql/version-cluster/timestamp.basebackup — the backup from pg_backupcluster ... basebackup. here's what's inside her:
    • config.tar.gz — tarball of the cluster configuration directory (postgresql.conf, pg_hba.conf, ...) in /etc/postgresql.
    • tablespace.tar.gz, pg_wal.tar.gz, backup_manifest — tablespace and WAL tarballs and backup info written by pg_basebackup.
    • status — completion timestamp of the backup run.
  • /var/backups/postgresql/version-cluster/timestamp.dump — the backup from pg_backupcluster ... dump. contents:
    • config.tar.gz — tarball of the cluster configuration directory (postgresql.conf, pg_hba.conf, ...) in /etc/postgresql.
    • createcluster.opts — options (encoding, locale, data checksums) to be passed to pg_createcluster for restoring this cluster.
    • globals.sql — global objects (roles, tablespaces) from pg_dumpall --globals-only.
    • databases.sql — SQL commands to create databases and restore database-level options.
    • database.dump — database dumps from pg_dump --format=custom.
    • status — completion timestamp of the backup run.
  • /var/backups/postgresql/version-cluster/wal — WAL files from pg_receivewal.

🙈 CAVEATS 🙈

okay listen, for dump-style backups, not all properties of the original cluster are preserved. important. keep reading:

  • In PostgreSQL 10 and earlier, ALTER ROLE ... IN DATABASE is not supported.
  • Not all initdb options are carried over. currently supported are --encoding, --lc-collate, --lc-collate, and -k --data-checksums.
⚠️ the earliest PostgreSQL version supported for dumps is 9.3. for basebackups, the earliest supported version is 9.1. receivewal (and hence archive recovery) are supported in 9.5 and later. don't try it on your ancient fossil, bestie 😭

👑 SEE ALSO 👑

pg_restorecluster(1), pg_dump(1), pg_dumpall(1), pg_basebackup(1), pg_receivewal(1), pg_archivecleanup(1).

💜 AUTHOR 💜

Christoph Berg <myon@debian.org> — the icon, the legend. 🫶

and that's the whole page, bestie!! this babe ships in Debian, dated 2026-07-28, and she's forever our PG_BACKUPCLUSTER(1). go make some backups, you're doing amazing sweetie 💖✨🎀

📦 where this page comes from