BARMAN-RESTORE(1)

📦
version 3.20.1 · 7 versions
, in epel 10, fedora 43, fedora 44

🦋 NAME 🦋

barman-restore — Barman Sub-Commands

okay so this is the page for the barman-restore sub-command, and it lives in the Barman manual — you'll find it filed as BARMAN-RESTORE(1) in section 1. it's the one that puts your Postgres backups back. we love a comeback story 💖

✨ SYNOPSIS ✨

          restore
              [ --aws-region AWS_REGION } ]
              [ --azure-resource-group AZURE_RESOURCE_GRP ]
              [ --bwlimit KBPS ]
              [ --exclusive ]
              [ --gcp-zone GCP_ZONE ]
              [ { --get-wal | --no-get-wal } ]
              [ { -h | --help } ]
              [ { -j | --jobs } PARALLEL_WORKERS ]
              [ --jobs-start-batch-period SECONDS ]
              [ --jobs-start-batch-size NUMBER ]
              [ --local-staging-path PATH ]
              [ { --network-compression | --no-network-compression } ]
              [ --no-retry ]
              [ --partial-wal ]
              [ --recovery-conf-filename FILENAME ]
              [ --recovery-staging-path PATH ]
              [ --staging-path STAGING_PATH ]
              [ --staging-location STAGING_LOCATION ]
              [ --combine-mode COMBINE_MODE ]
              [ --remote-ssh-command STRING ]
              [ --restore-command COMMAND ]
              [ --retry-sleep SECONDS ]
              [ --retry-times NUMBER ]
              [ --snapshot-recovery-instance INSTANCE_NAME ]
              [ --snapshot-recovery-zone GCP_ZONE ]
              [ --skip-archive-wal ]
              [ --standby-mode ]
              [ --tablespace NAME:LOCATION [ --tablespace NAME:LOCATION ... ] ]
              [ --target-action { pause | shutdown | promote } ]
              [ --target-immediate ]
              [ --target-lsn LSN ]
              [ --target-name RESTORE_POINT_NAME ]
              [ --target-time TIMESTAMP ]
              [ --target-tli TLI ]
              [ --target-xid XID ]
              [ --staging-wal-directory ]
              SERVER_NAME BACKUP_ID DESTINATION_DIR

(yes bestie, that lone } on the --aws-region line is exactly how it's written. we do not fix what we did not break 💅)

💜 DESCRIPTION 💜

okay so what does this thing actually do? barman-restore runs a PostgreSQL server restore operation. Barman takes the backup from a server and drops it into your destination directory. simple as that. 🎀

the restore can go down locally — right on the barman node itself — or remotely, on another machine you can reach over SSH. and what decides which one you get? literally one thing: whether or not you passed the --remote-ssh-command option. that's the whole vibe check. 🌈

want the full lore? it's all in the Recovery section. and psst — you can use a shortcut instead of BACKUP_ID. 👑

🌸 PARAMETERS 🌸

the positional trio 🫶

  • SERVER_NAME — the name of the server in the barman node.
  • BACKUP_ID — the id of the backup in the barman catalog. you can literally just write auto and Barman will go find the most suitable backup for the restore operation all by itself. main character behavior, honestly. ✨
  • DESTINATION_DIR — the destination directory where the backup gets restored.

the options 🧚

  • --aws-region — specify the AWS region where the instance and disks for snapshot recovery are located. this option lets you override the aws_region value in the Barman configuration.
  • --azure-resource-group — specify the Azure resource group containing the instance and disks for snapshot recovery. this one lets you override the azure_resource_group value in the Barman configuration.
  • --bwlimit — specify the maximum transfer rate in kilobytes per second. a value of 0 means no limit at all. this setting overrides the bandwidth_limit configuration option.
  • --delta-restore / --no-delta-restore — enable/disable usage of delta-restore for a delta recovery. the default is based on the recovery_options setting.
  • --exclusive — set the target (time, XID or LSN) to be non inclusive.
  • --gcp-zone — specify the GCP zone where the instance and disks for snapshot recovery are located. this option lets you override the gcp_zone value in the Barman configuration.
  • --get-wal / --no-get-wal — enable/disable usage of get-wal for WAL fetching during recovery. the default is based on the recovery_options setting.
note: when wals_directory is configured to use cloud storage (like S3, Azure, GCS), restores always require get-wal for WAL fetching. so if you specify --no-get-wal, or you just leave get-wal out of recovery_options, Barman will automatically enable get-wal for the restore operation and hit you with a warning. 😭 not the plot twist you asked for but ok.
  • --partial-wal — copy .partial WAL files to the recovery destination with the .partial suffix stripped. Barman looks at two sources here: .partial files in the streaming_wals_directory (written by pg_receivewal) and .partial files in the main WAL archive (archived during standby promotion, possibly compressed or encrypted). this is only applicable when you're using --no-get-wal. when --get-wal is used, .partial files are already handled transparently and this option has no effect. the flag also does nothing when --target-immediate is used, since recovery stops at the first consistent state before any partial WAL would even be needed. see Partial WAL files during recovery for the details. 🍓
  • -h, --help — show a help message and exit. gives you the info about command usage. the "bestie explain" button, basically.
  • -j, --jobs PARALLEL_WORKERS — specify the number of parallel workers to use for copying files during the backup. this setting overrides the parallel_jobs parameter if it's specified in the configuration file.
  • --jobs-start-batch-period — specify the time period, in seconds, for starting a single batch of jobs. this value overrides the parallel_jobs_start_batch_period parameter if it's set in the configuration file. the default is 1 second.
  • --jobs-start-batch-size — specify the maximum number of parallel workers to initiate in a single batch. this value overrides the parallel_jobs_start_batch_size parameter if it's defined in the configuration file. the default is 10 workers.
  • --local-staging-path — specify a path on the Barman host where the chain of backups will be combined before being copied to the destination directory. whatever contents get created inside the staging path will be removed once the restore process completes. this option is necessary for restoring from block-level incremental backups and has no effect otherwise.
deprecated since version 3.15: --local-staging-path is deprecated and will be removed in a future release. use --staging-path and --staging-location instead. 😭
  • --network-compression / --no-network-compression — enable/disable network compression during remote restore. the default is based on the network_compression configuration setting.
  • --no-retry — there will be no retry in case of an error. it's the same as setting --retry-times 0. one shot, no takebacks 💀
  • --recovery-conf-filename — specify the name of the file where Barman should write recovery options when recovering backups for Postgres versions 12 and later. by default this is set to postgresql.auto.conf. however, if --recovery-conf-filename is specified, recovery options will be written to the specified value instead. while the default value is suitable for most Postgres installations, this option lets you specify an alternative location if Postgres is managed by tools that alter the configuration mechanism — for example, if postgresql.auto.conf is symlinked to /dev/null. 🙈
  • --recovery-staging-path — specify a path on the recovery host where files for a compressed backup will be staged before being decompressed to the destination directory. backups get staged in their own directory within the staging path, following the naming convention barman-staging-SERVER_NAME-BACKUP_ID. this staging directory is removed after the restore process is complete. this option is mandatory for restoring from compressed backups and has no effect otherwise.
deprecated since version 3.15: --recovery-staging-path is deprecated and will be removed in a future release. use --staging-path and --staging-location instead. 😭
  • --staging-path — a path where intermediate files are staged during restore. when you're restoring a compressed backup, it serves as a temporary location for decompression before copying to the final destination. when you're restoring an incremental backup, it's where backups get combined before copying to the final destination. this location must have enough space to store the decompressed/combined backup. 🫶
  • --staging-location — specifies whether --staging-path is a local or remote path. valid values are local and remote.
  • --combine-mode — specifies a copy mode for pg_combinebackup when combining incremental backups during a restore. the options include:
    • copy (default): use standard file copying when combining incremental backups.
    • link: use hard links when combining incremental backups. reconstruction of the synthetic backup might be faster (no file copying) and use less disk space.
    • clone: use efficient file cloning (also known as "reflinks" on some systems) instead of copying files to the new data directory, which can result in near-instantaneous copying of the data files. ⚡
    • copy-file-range: use the copy_file_range system call for efficient copying. on some file systems this gives results similar to clone, sharing physical disk blocks, while on others it may still copy blocks, but do so via an optimized path.

refer to the pg_combinebackup documentation at https://www.postgresql.org/docs/current/app-pgcombinebackup.html for more details and restrictions of each mode. 📚

  • --remote-ssh-command — this option enables remote restore by specifying the secure shell command to execute on a remote host. it functions similarly to the ssh_command server option in the configuration file for remote restore, that is, 'ssh USER@SERVER'.
  • --restore-command — specify a custom restore command to override Barman's default restore_command in the PostgreSQL recovery configuration. while the default restore_command built by Barman is suitable for most cases, this option lets you specify an alternative command if your setup requires it. can be used only when running a restore with get-wal mode.
  • --retry-sleep — specify the number of seconds to wait after a failed copy before retrying. this setting applies to both backup and restore operations and overrides the basebackup_retry_sleep parameter if it's defined in the configuration file.
  • --retry-times — bestie, you get to say how many times Barman should retry the base backup copy if something goes 💀 wrong. This hits both the backup and the restore operations, and it overrides the basebackup_retry_times parameter if that one's set in the config file. So if your config says one thing and your flag says another, the flag wins. Periodt.
  • --snapshot-recovery-instance — drop the name of the instance where the disks recovered from the snapshots get attached. You need this one when you're recovering backups that were created with backup_method=snapshot. No instance name, no recovery, iykyk.
  • --snapshot-recovery-zone — (deprecated) the zone containing the instance and disks for the snapshot recovery. It's been replaced by --gcp-zone, so like… she's retired, respect the legacy, use the new one. 🎀
  • --standby-mode — do you want to start the Postgres server as a standby? Yes or no. That's it. That's the vibe check.
  • --tablespace — specify a tablespace relocation rule. NAME is the tablespace name, and LOCATION is the recovery host destination path where you want that tablespace restored. Match made in heaven 💖
  • --target-action — triggers a specific action the moment the recovery target is reached. Heads up: this option requires you to define a target along with one of these actions. The possible values are:
    • pause — once the recovery target is hit, the server starts up in pause state, so you can go inspect the instance like the little detective you are 🔍
    • promote — once the recovery target is hit, the server exits the recovery operation and gets promoted as a master. Main character promotion fr fr 👑
    • shutdown — once the recovery target is hit, the server just shuts down. Nap time. 😴
  • --target-immediate — recovery is done as soon as a consistent state is reached, which is the end of the base backup. We love a clean finish ✨
  • --target-lsn — recover to the exact LSN (Log Sequence Number) you specify. This one requires Postgres 10 or above, so check your version first bestie.
  • --target-name — recover to the specified name of a restore point that you previously created with the pg_create_restore_point(name) function. Named targets >>> everything.
  • --target-time — recover to the specified time. Use the format YYYY-MM-DD HH:MM:SS.mmm. Put it in exactly like that or it's giving chaos 💅
  • --target-tli — recover the specified timeline. Besides a numeric timeline ID, you can use the special values current and latest. Here's the tea on defaults:
    • For Postgres versions 12 and above, the default is to recover to the latest timeline in the WAL archive.
    • For Postgres versions below 12, the default is to recover to the timeline that was current at the time the backup was taken.
  • --target-xid — recover to the specified transaction ID. Simple, clean, iconic.
  • --skip-archive-wal — skip archiving staged WAL files before starting the restore. By default, barman restore archives any WAL files in the server's incoming/ streaming directory before restoring, which helps reduce RPO in DR scenarios. Use this option when you want to skip that step entirely. Sometimes you just gotta move fast 🏃‍♀️
  • --staging-wal-directory — a staging directory on the destination host for WAL files when you're doing PITR. If you don't specify one, it uses a barman_wal directory inside the destination directory. Default behaviour, cute behaviour 🌸

🎀 SHORTCUTS 🎀

Use shortcuts instead of BACKUP_ID. Yes, shortcuts. We're not typing a whole ID when a vibe word will do 💅

  • first / oldest — the oldest available backup for the server, in chronological order.
  • last / latest — the most recent available backup for the server, in chronological order.
  • last-full / latest-full — the most recent full backup taken with methods rsync or postgres.
  • last-failed — the most recent backup that failed, in chronological order. 😭 (we don't talk about her)

💖 Author 💖

EnterpriseDB

© Copyright EnterpriseDB UK Limited 2011-2026

okay bestie that's the whole page, you ate it 🫶 this was Barman 3.20, dated Sep 29, 2026, and it lives in section BARMAN-RESTORE(1). go restore something iconic, no cap 💅✨

📦 where this page comes from