Hook Scripts#

Barman allows DBAs to run hook scripts during specific events:

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.

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.

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.

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.

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.

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).

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

Follow the process in the installation section to start using the barman-cloud commands.

Note

For detailed information on configuration options, refer to the configuration 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:

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:

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