Backup export and import#

Overview#

Barman can export an existing backup as a single self-contained tarball and later import it back into the Barman catalog. This bridges Barman with enterprise data-management workflows that rely on external archival systems, for example writing long-term copies to tape or moving backups across storage tiers as part of a Grandfather/Father/Son strategy.

The exchange format is the following: the export is a tarball of files; the import only requires that the tarball is presented on disk to the target Barman server. Barman does not integrate with any specific external product: any system that can archive a file from disk and later restore it back can carry an exported backup end-to-end.

The outer tarball can optionally be compressed with the supporetd algorithms (gzip, bzip2 or xz). Compression applies only to the outer tarball: data files and WAL segments inside are not recompressed, and any compression they already carry (for example WAL or backup compression configured on the source server) is preserved as-is. On import, the compression format is detected automatically from the tarball and decompression is handled transparently.

Limitations#

Only full backups in DONE state can be exported or imported; incremental backup chains are currently not supported for this feature.
The feature is supported only on Barman servers using local storage.
The exported tarball is tied to the source cluster’s systemid; importing into a different cluster is not supported.
The original tarball filename must be preserved through the archival chain and renaming it breaks the integrity check.
Encryption is preserved transparently; encrypted backups are exported and imported as-is.

Tarball layout#

The exported tarball contains everything Barman needs to re-register and restore the backup:

backup-export-SERVER-BACKUP_ID-TIMESTAMP-CHECKSUM.tar[.gz|.bz2|.xz]
├── identity.json            # server identity
├── backup.info              # backup metadata
├── barman.json              # additional Barman metadata
├── backup/                  # backup data tree (PGDATA + tablespaces)
├── wals/<hash>/<wal_name>   # WAL segments required for consistency
└── xlog.db                  # WAL metadata

The symlinks normally found in pg_tblspc/ are not stored in the tarball: tablespace data is stored as plain subdirectories and the symlinks are reconstructed during import.

Tarball filename and integrity#

The filename follows the pattern:

backup-export-{SERVER_NAME}-{BACKUP_ID}-{TIMESTAMP}-{CHECKSUM}.tar[.gz|.bz2|.xz]

where TIMESTAMP is the export time in UTC (YYYYMMDDTHHMMSS) and CHECKSUM is the first eight characters of the SHA-256 hash of the whole tarball. When barman import-backup is run, it recomputes the SHA-256 of the file and compares it against the value embedded in the filename, refusing the import on mismatch.

Warning

Do not rename the exported tarball when transferring it through your archival system. Renaming breaks the integrity check and barman import-backup will refuse it. If your archival system stores files under a different name, restore them to the original name before importing.

Usage#

The following walk-through covers a full lifecycle: exporting a backup, handing it off to an external archival system, restoring it back to disk, and importing it into a Barman server for recovery.

Pick a full backup in DONE state on the source server:

barman list-backups main
barman show-backup main 20260513T101530

Export the backup to an existing directory. Optionally compress the outer tarball with --compression {gzip|bzip2|xz} and tune the level with --compression-level:
```
barman export-backup main 20260513T101530 /var/tmp/barman-exports
```
Barman writes a single file under /var/tmp/barman-exports whose name embeds the export timestamp and integrity checksum, for example:
```
backup-export-main-20260513T101530-20260513T134207-9f3a1c20.tar
```
Archive the tarball with your external backup product. Treat the file as opaque; the only requirement is that the original filename is preserved through the archival chain.
Restore the tarball back to disk on the target Barman server using your external product, into any directory of your choice.
Import the backup into the target catalog:
```
barman import-backup main \
    /var/tmp/barman-imports/backup-export-main-20260513T101530-20260513T134207-9f3a1c20.tar
```
The import is atomic: data is extracted into a staging directory under basebackups_directory, verified end-to-end, and only then moved into place. If any step fails, the staging directory and any partial WAL changes are cleaned up automatically and the catalog is left untouched.

On success, the backup is annotated with KEEP:STANDALONE so that retention policies will not remove it, and a warning is printed to make this visible. Use barman keep main BACKUP_ID --release if you want the imported backup to participate in retention again (see barman keep).

Verify and restore to confirm the imported backup is fully usable:

barman list-backups main
barman show-backup main 20260513T101530
barman restore main 20260513T101530 /var/lib/postgresql/recovered