BARMAN-CLOUD-WAL-ARCHIVE(1)

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

✨ NAME ✨

barman-cloud-wal-archive — it's one of the Barman-cloud Commands, bestie 💖

🌸 SYNOPSIS 🌸

okay so here's the whole vibe, no edits, exactly as it comes:

barman-cloud-wal-archive
                [ { -V | --version } ]
                [ --help ]
                [ { { -v | --verbose } | { -q | --quiet } } ]
                [ { -t | --test } ]
                [ --cloud-provider { aws-s3 | azure-blob-storage | google-cloud-storage } ]
                [ { { -z | --gzip } | { -j | --bzip2 } | --xz | --snappy | --zstd | --lz4 } ]
                [ --compression-level COMPRESSION_LEVEL ]
                [ --tag KEY,VALUE [ --tag KEY,VALUE ... ] ]
                [ --history-tag KEY,VALUE [ --history-tag KEY,VALUE ... ] ]
                [ --endpoint-url ENDPOINT_URL ]
                [ --addressing-style { auto | virtual | path } ]
                [ { -P | --aws-profile } AWS_PROFILE ]
                [ --profile AWS_PROFILE ]
                [ --read-timeout READ_TIMEOUT ]
                [ { -e | --encryption } ENCRYPTION ]
                [ --sse-kms-key-id SSE_KMS_KEY_ID ]
                [ --sse-customer-key SSE_CUSTOMER_KEY ]
                [ { --azure-credential | --credential } { azure-cli | managed-identity |
                  default } ]
                [ --encryption-scope ENCRYPTION_SCOPE ]
                [ --max-block-size MAX_BLOCK_SIZE ]
                [ --max-concurrency MAX_CONCURRENCY ]
                [ --max-single-put-size MAX_SINGLE_PUT_SIZE ]
                [ --kms-key-name KMS_KEY_NAME ]
                DESTINATION_URL SERVER_NAME [ WAL_PATH ]

🦋 DESCRIPTION 🦋

so barman-cloud-wal-archive is literally built to live inside the archive_command of a Postgres server and just, like, yeet your WAL files straight to cloud storage 🌈. no middleman, no drama.

📌 Note: if you're on Python 2 or any of the unsupported Python 3 versions, please don't touch the compression options --gzip or --bzip2. the script cannot restore gzip-compressed WALs on Python < 3.2, or bzip2-compressed WALs on Python < 3.3. it's giving "we tried to warn you" 💀

this script handles the direct transfer of WAL files to cloud storage, bypassing the Barman server entirely — main character energy fr fr. and bonus: you can also use it as a hook script for WAL archiving (pre_archive_retry_script) 👑

📌 Note: for GCP, the only authentication supported is via the GOOGLE_APPLICATION_CREDENTIALS env var. and if you need an alternative GCP universe (like S3NS/T-Systems), set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to whatever universe domain you want 🌌

🎀 PARAMETERS 🎀

  • SERVER_NAME — the name of the server whose WALs are getting archived 💜
  • DESTINATION_URL — the URL of your cloud destination, like a bucket in AWS S3. for example: s3://bucket/path/to/folder 🍓
  • WAL_PATH — the value of the '%p' keyword (as per archive_command) 🌸
  • -V / --version — show the version and dip 👋
  • --help — show this help message and exit.
  • -v / --verbose — turn the output verbosity up (like, -vv is more than -v) 🔥
  • -q / --quiet — turn the output verbosity down (so -qq is less than -q) 🙈
  • -t / --test — test your cloud connectivity and exit. vibe check, but for your bucket ✨
  • --cloud-provider — which cloud provider you're using as the storage backend.

allowed options are:

  • aws-s3.
  • azure-blob-storage.
  • google-cloud-storage.
  • -z / --gzip — gzip-compress the WAL while uploading it to the cloud 🗜️
  • -j / --bzip2 — bzip2-compress the WAL while uploading it to the cloud.
  • --xz — xz-compress the WAL while uploading it to the cloud.
  • --snappy — snappy-compress the WAL while uploading it to the cloud (needs the python-snappy Python library installed, no cap).
  • --zstd — zstd-compress the WAL while uploading it to the cloud (needs the zstandard Python library installed).
  • --lz4 — lz4-compress the WAL while uploading it to the cloud (needs the lz4 Python library installed).
  • --compression-level — the compression level for whichever compression algorithm you picked. valid values are integers inside the supported range of your chosen algorithm, or one of the predefined labels: low, medium, and high. the range of each algorithm, plus what level each predefined label maps to, lives in compression_level <#configuration-options-compression-level> 📊
  • --tag — a tag to be added to archived WAL files in cloud storage 🏷️
  • --tags — a tag to be added to archived WAL files in cloud storage.
📌 Note: if you're using --tags before the positional arguments, you must insert -- after it to mark the end of the optional arguments. that tells the parser to treat everything after -- as positional. without the --, Barman might go "hmm, these positional args look like values for the last option" and get it wrong 😭
⚠️ Deprecated since version 3.15: --tags is deprecated. use --tag instead.
  • --history-tag — a tag to be added to archived history files in cloud storage 🏷️
  • --history-tags — tags to be added to archived history files in cloud storage.
📌 Note: if you're using --history-tags before the positional arguments, you must insert -- after it to mark the end of optional arguments. that's how the parser knows to treat everything after -- as positional. without it, Barman may misinterpret positional arguments as values for the last option 🙈
⚠️ Deprecated since version 3.15: --history-tags is deprecated. use --history-tag instead.

🌈 Extra options for the AWS cloud provider 🌈

  • --endpoint-url — override the default S3 endpoint URL with this one you're giving it.
  • --addressing-style — the addressing style to use for S3 requests. super handy when you're connecting to S3-compatible services that are picky about 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 (like an INI section in your AWS credentials file).
  • --profile (deprecated) — profile name (like an INI section in your AWS credentials file) — replaced by --aws-profile.
  • --read-timeout — the time in seconds before a timeout is raised while waiting to read from a connection (defaults to 60 seconds) ⏱️
  • -e / --encryption — the encryption algorithm used when storing the uploaded data in S3.

allowed options:

  • AES256.
  • aws:kms.
  • --sse-kms-key-id — the AWS KMS key ID that should be used for encrypting the uploaded data in S3. you can pass just the key ID on its own, or the full ARN for the key. only allowed if -e / --encryption is set to aws:kms 🔐
  • --sse-customer-key — the customer-provided encryption key (SSE-C) to use for encrypting and decrypting data in S3. the value has to be a file:// URI pointing at a file containing a base64-encoded 256-bit (32-byte) key (e.g. file:///etc/barman/sse-c.b64). cannot be used together with --sse-kms-key-id or -e / --encryption 🚫
🚨 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 make barman commands fail when S3 rejects requests with a mismatched or missing key. like, genuinely do not do this one 💀

💜 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, 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 gets used for Azure Blob Storage too 🦋

allowed options are:

  • azure-cli.
  • managed-identity.
  • default.
  • --encryption-scope — the name of an encryption scope defined in the Azure Blob Storage service, which is what'll be used to encrypt the data in Azure 🔐
  • --max-block-size — the chunk size to use when uploading an object via the concurrent chunk method (default: 4MB).
  • --max-concurrency — the maximum number of chunks uploaded concurrently (default: 1).
  • --max-single-put-size — the maximum size for which the Azure client will upload an object in a single request (default: 64MB). if you set this lower than the Postgres WAL segment size after any applied compression, then the concurrent chunk upload method gets used for WAL archiving 📦

⭐ Extra options for GCP cloud provider ⭐

  • --kms-key-name — the name of the GCP KMS key that should be used for encrypting the uploaded data in GCS 🔑

👑 AUTHOR 👑

EnterpriseDB

© Copyright EnterpriseDB UK Limited 2011-2026

and that's the whole page, bestie 💖 this was barman-cloud-wal-archive from the Barman manual, version 3.20, dated Sep 29, 2026 — go archive some WALs, you're doing amazing sweetie 🫶✨🎀

📦 where this page comes from