Docs: Archive Path Seperation / Behavior for major cluster upgrades

[darioackermann]

The old Barman Cloud plugin does not automatically separate archives during major upgrades. To preserve pre-upgrade backups and keep archives clean, changing the serverName parameter is needed.

Is this also the case for the new plugin? I haven't found any documentation regarding that.

[dosubot]

Yes, the new barman-cloud plugin (CNPG-I) also does not automatically separate archives during major PostgreSQL upgrades. You still need to manually change the serverName plugin parameter to create a separate archive path [1].

Without doing this, you can run into timeline history file conflicts because pg_upgrade resets the timeline to 1, which causes replicas to fail with errors like "requested timeline 2 is not a child of this server's history" [2].

The recommended approach is to update the serverName parameter in the Cluster's plugin configuration before upgrading, e.g.:

plugins:
- name: plugin-barman-cloud
  enabled: true
  parameters:
    destinationPath: s3://my-bucket/
    serverName: cluster-example-pg17  # was cluster-example-pg16

This keeps your pre-upgrade backups intact at the old path while the upgraded cluster writes to a new one [1].

One thing to note: in the new plugin architecture, the serverName should be set in the Cluster plugin parameters, not in the ObjectStore resource (where it's retained only for API compatibility) [3]. A documentation update was also made to explicitly recommend using separate storage directories for major upgrades [4].

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.