.. _recovery: Recovery ======== The restore command is used to restore an entire Postgres server from a backup created with the backup command. To use it, run: ``barman restore [OPTIONS] SERVER_NAME [BACKUP_ID] DESTINATION_PATH`` It is possible to restore a backup without specifying the ``backup_id``. In this case, Barman will automatically choose the most suitable backup from the catalog. If no recovery target is provided, it will select the most recent available backup by default. If a recovery target is specified, Barman will use it to identify the appropriate backup based on the recovery criteria: * ``target_time``: Barman will retrieve the most recent backup available up to ``target_time``, e.g., ``2025-01-21 10:00:00``. * ``target_lsn``: Barman will retrieve the most recent backup available up to ``target_lsn``, e.g., ``3/64000000``. * ``target_tli``: Barman will retrieve the most recent backup available from timeline ``target_tli``, e.g., ``2``. * ``target_tli`` combined with one of the other two targets: Barman will retrieve the most recent backup available up to the ``target_lsn`` or ``target_time`` which belongs to the ``target_tli``, e.g., ``2025-01-21 10:00:00`` from timeline ``2``. .. note:: * Refer to :ref:`concepts-barman-concepts-restore-and-recover` for a clearer understanding of the recovery concept in Barman. * Do not run the restore command on a directory where a Postgres instance is currently running. Ensure Postgres is stopped before initiating recovery, including recovery of tablespace directories. * The backup is restored to the specified directory, which will be ready to start a Postgres instance. * Use the ``list-backups`` command to find the specific backup ID you need. * Barman does not track symbolic links inside PGDATA (except for tablespaces). Ensure you manage symbolic links and include them in your disaster recovery plans. * When restoring without specifying a ``backup_id``, Barman does not consider the :ref:`backup_method `. If the selected backup requires specific arguments or doesn't support certain options, the restoration may fail. In such cases, you will receive an error message that can help adjust the restore command accordingly. For example, ``--snapshot-recovery-instance`` is required when restoring a snapshot backup. .. _recovery-remote-recovery: Remote Recovery --------------- Use ``--remote-ssh-command COMMAND`` to perform recovery on a remote server via SSH. It's recommended to use the postgres user on the target node for remote recovery. **Known Limitations** * Requires at least 4GB of free space in the system's temporary directory unless ``get-wal`` is specified. * SSH must use public key authentication. * The remote user must be able to create the necessary directory structure. * Ensure there is enough free space on the remote server for the base backup and WAL files. .. _recovery-tablespace-remapping: Tablespace Remapping -------------------- Use ``--tablespace NAME:DIRECTORY`` to remap tablespaces to a new location. Barman will attempt to create the destination directory if it doesn't exist. .. important:: By default, tablespaces are restored to the same path they had on the source server. Be cautious when restoring a backup without any remapping to a destination where a Postgres instance already exists, as it can end up overriding existing tablespace directories. .. _recovery-point-in-time-recovery: Point-in-Time Recovery ---------------------- Specify a recovery ``target`` with one of the options: * ``--target-time``: Recover to a specific timestamp. * ``--target-xid``: Recover to a specific transaction ID. * ``--target-lsn``: Recover to a Log Sequence Number. * ``--target-name``: Recover to a named restore point. * ``--target-tli``: Recover to a specific timeline. * ``--target-immediate``: End recovery when a consistent state is reached. .. note:: * Recovery targets must be a value after the end of the backup. To recover to a point in time within a backup, use the previous backup. * Timezone defaults to the Barman host if not specified in ``--target-time``'s timestamp. * Use ``--exclusive`` to control whether to stop right before the target or including the target. * ``--target-tli`` sets the target timeline. Use numeric IDs or shortcut values (``latest`` or ``current``). * When at least one `--target-*` option is specified, a ``recovery.signal`` file is created by Barman when restoring the backup, which signals the server to start a targeted recovery. * When restoring without specifying a ``backup_id``, the only recovery targets allowed are: ``--target-time``, ``--target-lsn`` and ``--target-tli``. Note that ``--target-time`` and ``--target-lsn`` are mutually exclusive, while ``--target-tli`` can be used independently or together with ``--target-time`` or ``--target-lsn``. The previous targets can be used with a ``--target-action`` which can take these values: * ``shutdown``: Shut down Postgres when the target is reached. * ``pause``: Pause Postgres for inspection when the target is reached. * ``promote``: Promote Postgres to primary when the target is reached. You can also configure the instance as a standby by calling ``--standby-mode``. After the backup is restored, ensure you modify the configuration to connect to the intended upstream node before starting the restored node in recovery mode. .. note:: * When ``--standby-mode`` is specified, a ``standby.signal`` file is created instead of a ``recovery.signal`` file. * When using ``--standby-mode``, although possible, you are not expected to set any of the ``--target-*`` options. .. seealso:: For more information regarding Postgres recovery behavior, refer to `Archive Recovery `_ and `Recovery Target `_ .. _recovery-fetching-wals-from-barman: Fetching WALs from Barman ------------------------- Use ``--get-wal`` to configure Postgres to fetch WALs from Barman during recovery. If not set, Barman will copy all the WALs required for Postgres recovery as part of the restore command. .. note:: When using ``--no-get-wal`` with targets like ``--target-xid``, ``--target-name``, or ``--target-time``, Barman will copy the entire WAL archive to ensure availability. Another option is to include the ``recovery_options`` configuration at the global/server level prior to a recovery operation to retrieve WAL files during the recovery process, effectively turning the Barman server into a WAL hub for your servers. .. code-block:: text recovery_options = 'get-wal' If ``get-wal`` is included during restore, Barman will set up the ``restore_command`` to use either ``barman get-wal`` or ``barman-wal-restore`` to retrieve the required WAL files, depending on whether the recovery is local or remote. If ``get-wal`` is specified in ``recovery_options`` but not needed during a specific recovery, you can disable it using the ``--no-get-wal`` option with the restore command. Here's an example of a ``restore_command`` for **local recovery**: .. code-block:: text restore_command = 'sudo -u barman barman get-wal SERVER %f > %p' Remember that the :ref:`barman get-wal ` command should always be executed as the ``barman`` user, with the necessary permissions to access WAL files from the catalog, which is why ``sudo -u barman`` is used in this example. For remote recovery, setting ``recovery_options`` to ``get-wal`` will create a ``restore_command`` using the :ref:`commands-barman-cli-barman-wal-restore` script, which is designed to handle SSH connection errors more robustly. This script offers useful features like automatic compression and decompression of WAL files and the ``peek`` feature, allowing you to retrieve upcoming WAL files while Postgres is processing earlier ones, optimizing bandwidth between Postgres and Barman. ``barman-wal-restore`` is included in the ``barman-cli`` package. Here's an example of a ``restore_command`` for **remote recovery**: .. code-block:: text restore_command = 'barman-wal-restore -U barman backup SERVER_NAME %f %p' Here, ``backup`` refers to the host where Barman is installed. Since it communicates via SSH, SSH key authentication is required for the ``postgres`` user to log in as ``barman`` on the backup server. If you need to use a non-default SSH port, you can specify it with the ``--port`` option. To verify that ``barman-wal-restore`` can connect to the Barman server and that the required Postgres server is set up to send WAL files, use the following command: .. code-block:: text barman-wal-restore --test backup pg DUMMY DUMMY Here, ``backup`` refers to the host where Barman is installed, ``pg`` is the name of the Postgres server configured in Barman, and ``DUMMY`` acts as a placeholder (the script needs two arguments for the WAL file name and destination directory, which will be ignored). If everything is set up correctly, you should see: .. code-block:: text Ready to retrieve WAL files from the server pg For further details on the ``barman-wal-restore`` command, type ``man barman-wal-restore`` on the host where ``barman-cli`` was installed or refer to the :ref:`commands-barman-cli-barman-wal-restore` command reference. .. tip:: When both the ``pg_wal`` directory and the ``spool`` directory are located on the same filesystem, serving WAL files will be faster because the files are renamed rather than copied. However, if these directories are on different filesystems, there will be no performance improvement, as the operation will involve both copying the file and then removing the original. Be mindful of the filesystem locations to optimize WAL file management efficiency. .. _recovery-recovering-compressed-backups: Recovering Compressed Backups ----------------------------- If a backup is compressed using the ``backup_compression`` option, Barman can decompress it during restore. The process involves a few steps: 1. The compressed backup files are copied to a staging directory on either the local or remote server using Rsync. 2. These files are then decompressed to the restore destination directory. 3. For remote recovery, configuration files requiring special handling are copied from the restore destination directory to a local temporary directory in the barman node, edited and mangled as needed, and then returned to the restore directory using Rsync. For local recovery, the local temporary directory is the restore destination itself, so editing and mangling operations are done in place. This intermediate step is necessary because Barman can only access individual files in the restore directory, as the backup directory contains only a compressed tarball file. 4. The staging directory is removed after restore is complete. Since Barman does not have knowledge of the deployment environment, it depends on the ``recovery_staging_path`` option to determine an appropriate location for the staging directory. Set the option in the global/server configuration or use the ``--recovery-staging-path`` option with the barman restore command. Failing to do so will result in an error, as Barman cannot guess a suitable location on its own. .. _recovery-recovering-block-level-incremental-backups: Recovering block-level incremental Backups ------------------------------------------ If you are recovering from a block-level incremental backup, Barman combines the backup chain using ``pg_combinebackup``. This chain consists of the root backup and all subsequent incremental backups up to the one being recovered. To successfully recover from a block-level incremental backup, you must specify the ``local_staging_path`` in the global/server configuration or use the ``--local-staging-path`` option with the barman restore command. Failing to do so will result in an error, as Barman cannot automatically determine a suitable staging location. The process involves the following steps: 1. Barman creates a synthetic backup by combining the chain of backups. This is done in a staging directory on the Barman server using ``pg_combinebackup``. Barman will create a subfolder inside the staging directory with the ID of the backup. 2. If the recovery is local, the synthetic backup is moved directly to the target location. If it is a remote recovery, the synthetic backup is transferred to the target location using Rsync. 3. After the restore is complete, the temporary subfolder in the local staging directory used for combining backups is removed. The local staging directory itself is kept. .. important:: If any backups in the chain were taken with checksums disabled, but the final backup has checksums enabled, the resulting syntethic backup may contain pages with invalid checksums. Please refer to the limitations in the `pg_combinebackup documentation `_ for more details. .. _recovery-limitation-of-partial-wal-files: Limitations of .partial WAL files --------------------------------- When using ``streaming_archiver``, Barman relies on ``pg_receivewal`` to continuously receive transaction logs from a Postgres server (either master or standby) through the native streaming replication protocol. By default, ``pg_receivewal`` writes these logs to files with a ``.partial`` suffix, indicating they are not yet complete. Barman looks for these ``.partial`` files in the ``streaming_wals_directory``. Once ``pg_receivewal`` completes the file, it removes the ``.partial`` suffix and hands it over to Barman's ``archive-wal`` command for permanent storage and compression. If the master Postgres server suddenly fails and cannot be recovered, the ``.partial`` file that was streamed to Barman may contain crucial data that might not have been delivered to the archiving process. Starting with Barman version 2.10, the ``get-wal`` command can retrieve the content of the current ``.partial`` WAL file using the ``--partial`` or ``-P`` option. This is useful for recovery, whether performing a full restore or a point-in-time recovery. When you initiate a restore command with ``get-wal`` and without ``--standby-mode``, Barman will automatically include the ``-P`` option in the ``barman-wal-restore`` command to handle the ``.partial`` file. Moreover, ``get-wal`` will check the ``incoming`` directory for any WAL files that have been sent to Barman but not yet archived. .. _recovery-managing-external-configuration-files: Managing external configuration files ------------------------------------- Barman restores external configuration files differently depending on how the backup was originally taken. When restoring a ``rsync`` backup, external files are restored into the :term:`PGDATA` directory via rsync, and not in the original location. A warning is issued regarding potentially risky settings, including the ones related to configuration files. In contrast, when restoring a ``postgres`` backup, external files are not restored as they were not backed up. A warning is provided to inform the user about the files that were not restored. Refer to the :ref:`Managing external configuration files ` section in the backup chapter to understand how external files are handled when creating a backup. .. _recovery-recovering-from-snapshot-backups: Recovering from Snapshot Backups -------------------------------- Barman currently does not support fully automated recovery from snapshot backups. This limitation arises because snapshot recovery requires provisioning and managing new infrastructure, a task best handled by dedicated :term:`IAC` solutions like Terraform or OpenTofu. However, you can still use the barman restore command to validate the snapshot recovery instance and perform post-recovery tasks, such as checking the Postgres configuration for unsafe settings and configuring any necessary PITR options. The command will also copy the ``backup_label`` file into place, as this file is not included in the volume snapshots, and will transfer any required WAL files--unless the ``--get-wal`` recovery option is specified, in which case it configures the Postgres ``restore_command`` to fetch the WALs. If restoring from a backup created with ``barman-cloud-backup``, you should use the ``barman-cloud-restore`` command instead of ``barman restore``. .. note:: The same requirements and configurations apply for restore when working with a cloud provider. See the ``Requirements and Configuration`` section and the specific cloud provider you are working with in the :ref:`Cloud Snapshot Backups ` section. Recovery Steps """""""""""""" 1. Provision a new disk for each snapshot taken during the backup. 2. Provision a compute instance to which each disk from step 1 is attached and mounted according to the backup metadata. 3. Use the ``barman restore`` or ``barman-cloud-restore`` command to validate and finalize the recovery. Steps 1 and 2 are ideally managed by an existing IAC system, but they can also be performed manually or via a custom script. Helpful Resources """"""""""""""""" `Example recovery script for GCP `_. `Example runbook for Azure `_. These resources make assumptions about your backup and recovery environment and should be customized before use in production. Running the restore command """""""""""""""""""""""""""" Once the recovery instance is provisioned and the disks cloned from the backup snapshots are attached and mounted, execute the barman restore command with the following additional arguments: * ``--remote-ssh-command``: The SSH command required to log into the recovery instance. * ``--snapshot-recovery-instance``: The name of the recovery instance as specified by your cloud provider. * Any additional arguments specific to the snapshot provider. Example Command ^^^^^^^^^^^^^^^ .. code:: bash barman restore SERVER_NAME BACKUP_ID REMOTE_RECOVERY_DIRECTORY \ --remote-ssh-command 'ssh USER@HOST' \ --snapshot-recovery-instance INSTANCE_NAME Barman will automatically recognize the backup as a snapshot and verify that the attached disks were cloned from the corresponding snapshots. It will then prepare Postgres for recovery by copying the backup label and WALs into place and adjusting the Postgres configuration with the necessary recovery options. Provider-Specific Arguments ^^^^^^^^^^^^^^^^^^^^^^^^^^^ For GCP: * ``--gcp-zone``: The availability zone where the recovery instance is located. If omitted, Barman will use the ``gcp_zone`` value set in the server config. For Azure: * ``--azure-resource-group``: The resource group for the recovery instance. If not provided, Barman will refer to the ``azure_resource_group`` value in the server config. For AWS: * ``--aws-region``: The AWS region of the recovery instance. If not specified, Barman will default to the ``aws_region`` value set in the server config.