.. _hook-scripts:

Hook Scripts
============

Barman allows :term:`DBAs <DBA>` to run hook scripts during specific events:

* :ref:`Before and after creating a backup <hook-scripts-before-and-after-creating-a-backup>`.
* :ref:`Before and after deleting a backup <hook-scripts-before-and-after-deleting-a-backup>`.
* :ref:`Before and after a WAL file is archived <hook-scripts-before-and-after-a-WAL-file-is-archived>`.
* :ref:`Before and after a WAL file is deleted <hook-scripts-before-and-after-a-WAL-file-is-deleted>`.
* :ref:`Before and after restoring a backup <hook-scripts-before-and-after-restoring-a-backup>`.

.. important::
  These scripts can be configured using the global options, which can be overridden for
  individual servers. Deletion and recovery hook scripts were introduced in ``version 2.4``.
  
There are two types of hook scripts that Barman can manage:

* **Standard Hook Scripts**: These scripts are executed once and do not have their
  return codes checked.

* **Retry Hook Scripts**: These scripts might be executed multiple times, depending on
  their return codes.

When executing a retry hook script, Barman checks the return code and will continue to
retry the script until it returns one of the following:

* ``SUCCESS`` (standard return code ``0``)
* ``ABORT_CONTINUE`` (return code ``62``)
* ``ABORT_STOP`` (return code ``63``)

Any other return code is treated as a transient failure, prompting Barman to retry the
script. This gives users greater control, allowing hook scripts to determine if a
failure should be considered transient. Additionally, for a pre-hook script, returning
``ABORT_STOP`` allows users to request that Barman interrupts the main operation with a
failure.

Hook scripts are executed in the following sequence (skipped if not present):

1. **Standard pre hook script**.

2. **Retry pre hook script**.

3. **Main event** (backup operation, restore operation or WAL archiving), unless the
   retry pre hook script was aborted with ``ABORT_STOP``.

4. **Retry post hook script**.

5. **Standard post hook script**.

All output generated by hook scripts is logged in Barman's log file..

.. note::
  Currently, ``ABORT_STOP`` is ignored by retry post-hook scripts. In such cases, this
  will result in logging an additional warning, and ``ABORT_STOP`` will behave the same
  as ``ABORT_CONTINUE``.

.. _hook-scripts-before-and-after-creating-a-backup:

Before and after creating a backup
----------------------------------

* ``pre_backup_script``: A hook script executed once before a base backup, without
  checking the exit code.
* ``pre_backup_retry_script``: A retry hook script executed before a base backup, 
  running repeatedly until it succeeds or is aborted.
* ``post_backup_retry_script``: A retry hook script executed after a base backup, 
  running repeatedly until it succeeds or is aborted.
* ``post_backup_script``: A hook script executed once after a base backup, without
  checking the exit code.

The shell environment will include the following variables for **backup scripts**:

* ``BARMAN_BACKUP_DIR``: The destination directory for the backup.
* ``BARMAN_BACKUP_ID``: The ID of the backup.
* ``BARMAN_CONFIGURATION``: The configuration file used by Barman.
* ``BARMAN_ERROR``: Any error message (only applicable in the ``post`` phase).
* ``BARMAN_PHASE``: Indicates the phase of the script, either ``pre`` or ``post``.
* ``BARMAN_PREVIOUS_ID``: The ID of the previous backup, if available.
* ``BARMAN_RETRY``: Set to ``1`` if it is a retry script; otherwise, it is ``0``.
* ``BARMAN_SERVER``: The name of the server.
* ``BARMAN_STATUS``: The status of the backup.
* ``BARMAN_VERSION``: The version of Barman.

.. _hook-scripts-before-and-after-deleting-a-backup:

Before and after deleting a backup
----------------------------------

* ``pre_delete_script``: A hook script triggered once before the backup deletion, with
  no exit code check.
* ``pre_delete_retry_script``: A retry hook script that runs before the backup deletion,
  executing repeatedly until it succeeds or is aborted.
* ``post_delete_retry_script``: A retry hook script that runs after the backup deletion,
  executing repeatedly until it succeeds or is aborted.
* ``post_delete_script``: A hook script triggered once after the backup deletion, with
  no exit code check.

**Delete scripts** utilize the same environmental variables as **backup scripts**, plus:

``BARMAN_NEXT_ID``: The ID of the next backup, if available.

.. _hook-scripts-before-and-after-a-WAL-file-is-archived:

Before and after a WAL is archived
----------------------------------

* ``pre_archive_script``: A hook script that runs once before a WAL file is archived by
  maintenance (typically via Barman cron), without checking the exit code.
* ``pre_archive_retry_script``: A retry hook script that executes before a WAL file is
  archived by maintenance, running repeatedly until it succeeds or is aborted.
* ``post_archive_retry_script``: A retry hook script that executes after a WAL file is
  archived by maintenance, running repeatedly until it succeeds or is aborted.
* ``post_archive_script``: A hook script that runs once after a WAL file is archived by
  maintenance, without checking the exit code.

**WAL archive scripts** share several environmental variables with **backup scripts**:

* ``BARMAN_CONFIGURATION``: The configuration file used by Barman.
* ``BARMAN_ERROR``: Any error message generated (only for the post phase).
* ``BARMAN_PHASE``: The phase of the script, either pre or post.
* ``BARMAN_SERVER``: The name of the server.

Additionally, the following variables are specific to **WAL archive scripts**:

* ``BARMAN_SEGMENT``: The name of the WAL file.
* ``BARMAN_FILE``: The full path of the WAL file.
* ``BARMAN_SIZE``: The size of the WAL file.
* ``BARMAN_TIMESTAMP``: The timestamp of the WAL file.
* ``BARMAN_COMPRESSION``: The type of compression applied to the WAL file.

.. _hook-scripts-before-and-after-a-WAL-file-is-deleted:

Before and after a WAL file is deleted
--------------------------------------

* ``pre_wal_delete_script``: A hook script that runs before a WAL file is deleted.
* ``pre_wal_delete_retry_script``: A retry hook script that executes before the deletion
  of a WAL file, running repeatedly until it succeeds or is aborted.
* ``post_wal_delete_retry_script``: A retry hook script that runs after a WAL file is
  deleted, executing repeatedly until it succeeds or is aborted.
* ``post_wal_delete_script``: A hook script that runs after a WAL file is deleted.

**WAL delete scripts** utilize the same environmental variables as
**WAL archive scripts**.

.. _hook-scripts-before-and-after-restoring-a-backup:

Before and after restoring a backup
-----------------------------------

* ``pre_recovery_script``: A hook script that runs once before a backup restore,
  without checking the exit code.
* ``pre_recovery_retry_script``: A retry hook script that executes before a backup
  restore, running repeatedly until it succeeds or is aborted.
* ``post_recovery_retry_script``: A retry hook script that runs after a backup restore,
  executing repeatedly until it succeeds or is aborted.
* ``post_recovery_script``: A hook script that runs once after a backup restore,
  without checking the exit code.

**Recovery scripts** utilize the same environmental variables as **backup scripts**,
plus:

* ``BARMAN_DESTINATION_DIRECTORY``: The directory where the new instance is restored.
* ``BARMAN_TABLESPACES``: The tablespace relocation map (in JSON format, if applicable).
* ``BARMAN_REMOTE_COMMAND``: The secure shell command used during restore (if
  applicable).
* ``BARMAN_RECOVER_OPTIONS``: Additional recovery options (in JSON format, if
  applicable).

.. _hook-scripts-using-barman-cloud-scripts-as-hooks-in-barman:

Using ``barman-cloud-*`` scripts as hooks in barman
---------------------------------------------------

Follow the process in the :ref:`installation section <installation>` to start using the
:ref:`barman-cloud commands <barman-cloud-commands-reference>`.

.. note::
    For detailed information on configuration options, refer to the
    :ref:`configuration <configuration-options-cloud-backups>` section.

You can use ``barman-cloud-backup`` as a ``post-backup script`` for the following Barman
backup types:

* Backups created with ``backup_method = rsync``.
* Backups created with ``backup_method = postgres`` when ``backup_compression`` is not
  applied.

To configure this, add the following line to your server configuration in Barman:

.. code-block:: text

    post_backup_retry_script = barman-cloud-backup [ OPTIONS ] DESTINATION_URL SERVER_NAME

.. warning::
    When used as a hook script, ``barman-cloud-backup`` requires the backup status to be
    ``DONE``. It will fail if the backup has any other status. To avoid issues, it is
    recommended to run backups with the ``-w`` / ``--wait`` option to ensure the hook
    script is not executed while the backup status is ``WAITING_FOR_WALS``.

Additionally, set up ``barman-cloud-wal-archive`` as a pre-WAL archive script by
adding the following line to the Barman configuration for your Postgres server:

.. code-block:: text

    pre_archive_retry_script = barman-cloud-wal-archive [ OPTIONS ] DESTINATION_URL SERVER_NAME

