Barman release notes

© Copyright EnterpriseDB UK Limited 2025 - All rights reserved.

3.13.0 (2025-02-20)

Notable changes

• Add new xlogdb_directory configuration

  Introduces a new xlogdb_directory configuration option. This parameter can be
  set either globally or per-server, and allows you to specify a custom directory
  for the xlog.db file. This file stores metadata of archived WAL files and is used
  internally by Barman in various scenarios. If unset, it defaults to the value of
  wals_directory. Additionally, the file was also renamed to contain the server name
  as a prefix.

  References: BAR-483.

• Make "backup_id" optional when restoring a backup

  Historically, Barman always required a "backup_id" to restore a backup, and would
  use that backup as the source for the restore.

  This feature removes the need for specifying which backup to use as a source for
  restore, making it optional.

  This change applies to both Barman and the barman-cloud scripts.

  Now the user is able to restore a backup in the following ways:

  1. Provide a "backup_id"
  2. Do not provide a "backup_id". It will retrieve the most recent backup
  3. Do not provide a "backup_id", but provide a recovery target, such as:
     - "target_time" (mutually exclusive with target_lsn)
     Will get the closest backup prior to the "target_time"
     - "target_lsn" (mutually exclusive with "target_time")
     Will get the closest backup prior to the "target_lsn"
     - "target_tli" (can be used combined with "target_time" or "target_lsn")
     Will get the most recent backup that matches the timeline. If combined with
     other recovery targets, it will get the most recent backup prior to the
     target_time or target_lsn that matches the timeline

  The recovery targets --target-xid, --target-name and --target-immediate
  are not supported, and will error out with a message if used.

  This feature will provide flexibility and ease when restoring a postgres cluster.

  References: BAR-541, BAR-473.

Minor changes

• Add current active model to barman show-server and barman status

  Previously, after applying a configuration model, the only way to check
  which model is currently active for a server was via the barman diagnose
  command. With this update, the barman status and barman show-server
  commands now also display the current active configuration model for a
  server, if any.

  References: BAR-524, BAR-400.

• Add --staging-wal-directory option to barman restore command to allow alternative WAL directory on PITR

  A new command line option --staging-wal-directory was added to the restore/recover
  command to allow an alternative destination directory for WAL files when performing
  PITR. Previously, WAL files were copied to a barman_wal directory within
  the restore destination directory. This enhancement provides greater flexibility, such as
  storing WALs on separate partitions during recovery.

  References: BAR-224.

• Pin boto3 version to any version <= 1.35.99

  Boto3 version 1.36 has changed the way S3 integrity is checked making this version
  incompatible with the current Barman code, generating the following error:

  An error occurred (MissingContentLength) when calling the PutObject operation

  As a temporary workaround, the version for boto3 is pinned to any version <= 1.35.99
  until support for 1.36 is implemented in Barman.

  References: BAR-535.

• Make barman-wal-archive smarter when dealing with duplicate WAL files

  Under some corner cases, Postgres could attempt to archive the same WAL twice.
  For example: if barman-wal-archive copies the WAL file over to the Barman host,
  but the script is interrupted before reporting success to Postgres. New executions
  of barman-wal-archive could fail when trying to archive the same file again
  because the WAL was already copied from Postgres to Barman, but not yet processed by
  the asynchronous Barman WAL archiver.

  This minor change deals with this situation by verifying the checksum of the
  existing and the incoming file. If the checksums match the incoming file is
  ignored, otherwise an output info message is sent and the incoming file is moved to
  the errors directory. The code will exit with 0 in both situations, avoiding WALs
  piling up in the Postgres host due to a failing archive_command.

  References: BAR-225.

• Document procedure to clear WAL archive failure check

  While redesigning the Barman docs we missed adding a note advising
  users to run a switch-wal command if the server is idle and
  barman check returns a failure on "WAL archiving".

  This addresses the gap left from the previous documentation.

  References: BAR-521.

• Delete WALs by deleting the entire directory at once, when possible

  Previously, when WAL files needed to be deleted (e.g., due to deletion of a backup),
  Barman would iterate over every WAL file and delete them individually. This could
  cause performance issues, mainly in systems which use ZFS filesystem. With this
  change, the entire directory will be deleted whenever noticed that all files in
  the directory are no longer needed by Barman.

  References: BAR-511.

• Add support for DefaultAzureCredential option on Azure authentication

  Users can now explicitly use Azure's DefaultAzureCredential for authentication
  by using the default option for azure_credential in the server configuration
  or the --azure-credential default option in the case of barman-cloud-*.
  Previously, that could only be set as a fallback when no credential was provided
  and no environment variables were set.

  References: BAR-539.

• Improve diagnose output for retention policy info

  Improves the output of the barman diagnose command to display a more user-friendly
  string representations. Specifically, "REDUNDANCY 2" is shown instead of
  "redundancy 2 b" for the 'retention_policy' attribute, and "MAIN" is shown instead
  of "simple-wal 2 b" for the 'wal_retention_policy' attribute.

  References: BAR-100.

Bugfixes

• Fix PITR when using barman restore with --target-tli

  Barman was not creating the recovery.signal nor filling recovery_target_timeline
  in postgresql.auto.conf in these cases:

  • The only recovery target passed to barman restore was --target-tli; or
  • --target-tli was specified with some other --target-* option, but the
    specified target timeline was the same as the timeline of the chosen backup.

  Now, if any --target-* option is passed to barman restore, that will be
  correctly treated as PITR.

  References: BAR-543.

• Fix bug when AWS 'profile' variable is referenced before assignment

  An issue was introduced by BAR-242 as part of the Barman 3.12.0 release.
  The issue was causing barman-cloud-backup-delete (and possibly other
  commands) to fail with errors like this when --aws-profile argument or
  aws_profile configuration were not set:

  ERROR: Barman cloud backup delete exception: local
  variable 'profile' referenced before assignment`

  References: BAR-518.

• Fix --zstd flag on barman-cloud-wal-archive

  Fixed a bug with the --zstd flag on barman-cloud-wal-archive where it was
  essentially being ignored and not really compressing the WAL file before upload.

  References: BAR-567.