BARMAN-CLOUD-BACKUP-DELETE(1)

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

💖 BARMAN-CLOUD-BACKUP-DELETE 💖

okay so bestie, welcome to the barman-cloud-backup-delete manual page — it's one of the Barman-cloud Commands, and no cap, it's the one that does the spring cleaning in your cloud storage. Let's get into it ✨

✨ SYNOPSIS ✨

barman-cloud-backup-delete
                [ { -V | --version } ]
                [ --help ]
                [ { { -v | --verbose } | { -q | --quiet } } ]
                [ { -t | --test } ]
                [ --cloud-provider { aws-s3 | azure-blob-storage | google-cloud-storage } ]
                [ --endpoint-url ENDPOINT_URL ]
                [ --addressing-style { auto | virtual | path } ]
                [ { -r | --retention-policy } RETENTION_POLICY ]
                [ { -m | --minimum-redundancy } MINIMUM_REDUNDANCY ]
                [ { -b | --backup-id } BACKUP_ID]
                [ --dry-run ]
                [ --check-object-lock ]
                [ { -P | --aws-profile } AWS_PROFILE ]
                [ --profile AWS_PROFILE ]
                [ --read-timeout READ_TIMEOUT ]
                [ --sse-customer-key SSE_CUSTOMER_KEY ]
                [ { --azure-credential | --credential } { azure-cli | managed-identity | default } ]
                [--batch-size DELETE_BATCH_SIZE]
                SOURCE_URL SERVER_NAME

🌸 DESCRIPTION 🌸

So barman-cloud-backup-delete is literally the script that deletes one or more backups that were made with the barman-cloud-backup command, pulling them out of cloud storage — and it also clears out the associated WAL files while it's at it. Two birds, one iconique little command 🦋

You can tell it what to delete in two ways, and honestly both are giving:

  • by backup ID (the kind you'd get from barman-cloud-backup-list), or
  • by a retention policy.

Retention policies here mirror the ones the Barman server uses — they delete every backup that isn't required to satisfy the policy you specified. And the moment a backup gets deleted, any unused WAL files tied to that backup get swept away too. periodt 🧹

Now, WALs count as unused if:

  • The WALs predate the begin_wal value of the oldest remaining backup.
  • The WALs are not required by any archival backups stored in the cloud.
Note: For GCP, only authentication with the GOOGLE_APPLICATION_CREDENTIALS env is supported. If you wanna use an alternative GCP universe (like S3NS/T-Systems), set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to the universe domain you want. ✨
Important: Every single backup deletion is actually three separate requests to the cloud provider — one for the backup files, one for the backup.info file, and one for the associated WALs. So if you delete by retention policy and you've got a whole pile of backups accumulated in cloud storage, you might be looking at a high volume of delete requests. 💀
Important: Starting with AWS boto3 1.36, the behavior of Data Integrity Protection checks has changed. Some methods used by Barman no longer require the Content-MD5 header. This means S3-compatible storage providers that haven't updated their server-side code may fail when used with newer boto3 versions. For example, MinIO addressed this change shortly after the boto3 1.36 announcement. If you're on MinIO, you must upgrade to the latest release (or at least RELEASE.2025-02-03T21-03-04Z or newer) to make sure everything's compatible and you don't hit failures. 🙈

🎀 PARAMETERS 🎀

  • SERVER_NAME — the name of the server that's holding the backup you wanna delete.
  • SOURCE_URL — the URL of the cloud source, like a bucket in AWS S3. For example: s3://bucket/path/to/folder.

💅 OPTIONS 💅

  • -V, --version — show the version and dip. 👋
  • --help — show this help message and exit.
  • -v, --verbose — turn the output verbosity up (so like, -vv is more than -v).
  • -q, --quiet — turn the output verbosity down (so -qq is less than -q).
  • -t, --test — test the cloud connectivity and exit. vibe check, basically ✅
  • --cloud-provider — the cloud provider you're using as a storage backend. Allowed options are:
    • aws-s3.
    • azure-blob-storage.
    • google-cloud-storage.
  • -b, --backup-id — the ID of the backup to be deleted. You can use a shortcut instead of the backup ID. 🫶
  • -m, --minimum-redundancy — the minimum number of backups that should always be available.
  • -r, --retention-policy — if you specify this, it deletes all backups that are eligible for deletion according to the retention policy you handed over. Syntax: REDUNDANCY value | RECOVERY WINDOW OF value { DAYS | WEEKS | MONTHS }
  • --batch-size — the maximum number of objects to be deleted in a single request to the cloud provider. If it's unset, then the maximum allowed batch size for the cloud provider you specified gets used (1000 for aws-s3, 256 for azure-blob-storage and 100 for google-cloud-storage).
  • --dry-run — find the objects that need to be deleted but don't actually delete them. window shopping, but for destruction 🔥

🌈 EXTRA OPTIONS FOR THE AWS CLOUD PROVIDER 🌈

  • --check-object-lock — check whether backup files are protected by S3 Object Lock before even attempting deletion. Turn this on when your S3 bucket has Object Lock configured and you want to make sure deletion operations respect object-level retention policies. If any base backup file is locked (whether by an active retention period or a legal hold), the deletion gets aborted with an error. 😭

For performance reasons, lock checks are only performed for base backup files, since once the base backup is removed, the corresponding WAL files aren't useful anymore. Heads up though: this check requires one request per file to check the lock status, which may make deletion take longer for backups with lots of files. This feature is only available for AWS S3-compatible object stores, and it also requires the s3:GetObjectRetention and s3:GetObjectLegalHold IAM permissions. 🔑

  • --endpoint-url — override the default S3 endpoint URL with the one you give it.
  • --addressing-style — the addressing style to use for S3 requests. This is useful when you're connecting to S3-compatible services that require a specific addressing style. Allowed options are:
    • auto (default): uses the addressing style determined by the underlying library.
    • virtual: uses virtual-hosted style addressing (e.g., bucket-name.s3.amazonaws.com).
    • path: uses path-style addressing (e.g., s3.amazonaws.com/bucket-name).
  • -P, --aws-profile — profile name (e.g. INI section in the AWS credentials file).
  • --profile (deprecated) — profile name (e.g. INI section in the AWS credentials file) — replaced by --aws-profile. it's giving legacy, bestie, use the other one 💀
  • --read-timeout — the time in seconds until a timeout is raised when waiting to read from a connection (defaults to 60 seconds).
  • --sse-customer-key — the customer-provided encryption key (SSE-C) to use for decrypting data in S3. The value must be a file:// URI pointing to a file containing a base64-encoded 256-bit (32-byte) key (e.g. file:///etc/barman/sse-c.b64).
Important: All backups and WAL files for a given server must be encrypted with the same SSE-C key. Mixing SSE-C-encrypted and unencrypted objects, or using different keys across backups, will cause barman commands to fail when S3 rejects requests with a mismatched or missing key. 🚨

🦋 EXTRA OPTIONS FOR THE AZURE CLOUD PROVIDER 🦋

  • --azure-credential, --credential — optionally specify the type of credential to use when authenticating with Azure. If you omit it, then Azure Blob Storage credentials get pulled from the environment, and the default Azure authentication flow is used for authenticating with all other Azure services. And if no credentials can be found in the environment, then the default Azure authentication flow also gets used for Azure Blob Storage. slay, it just figures it out ✨

Allowed options are:

  • azure-cli.
  • managed-identity.
  • default.

👑 AUTHOR 👑

EnterpriseDB

© Copyright EnterpriseDB UK Limited 2011-2026

and that's the whole page, bestie 🎀 this is barman-cloud-backup-delete from version 3.20, dated Sep 29, 2026, brought to you by the lovely people at EnterpriseDB — go forth and delete responsibly, mwah 💅💖

📦 where this page comes from