Support for PostgreSQL’s System identifier in Barman

The latest Barman 2.10 release introduces support for the system identifier of a PostgreSQL instance.
In this article, I will answer a few questions explaining what a system identifier is and why it is a good thing that Barman uses it.

What is the PostgreSQL system identifier?

PostgreSQL gives a unique system identifier to every database server (instance) when it is initialized to ensure it matches up WAL files with the installation that produced them.
When you make a physical backup the system identifier will be preserved also if a new instance will be created from that backup either if it’s a standby or not.

How can I retrieve the system identifier?

To retrieve the system identifier on a PostgreSQL instance, you can use `pg_controldata` or query the database.

pg_controldata

The `pg_controldata` command will return many pieces of information of the cluster and also the system identifier.

-shell$ pg_controldata
...
Database system identifier: 6771759591265590184
...

PostgreSQL query

One other way is to query directly the database.
Using the function pg_control_system() we are able to get, among other information, also the system_identifier.

-shell$ psql -c "SELECT system_identifier FROM pg_control_system()"
system_identifier
---------------------
6771759591265590184

PostgreSQL query through streaming replication protocol

PostgreSQL streaming replication protocol has one command called IDENTIFY_SYSTEM to return the system identifier. The following example query will return the system identifier, the current timeline ID, the current WAL flush location, and the connected database, where applicable:

-shell$ psql replication=1 -c "IDENTIFY_SYSTEM"
systemid            | timeline | xlogpos    | dbname
--------------------+----------+------------+--------
6771759591265590184 |        1 | 0/A04A38D0 |

How does Barman use the system identifier?

Barman stores the system identifier in the server directory (identity.json) when it performs the first backup. Barman compares the system identifier that it gets from the active connections (standard and replication) with the stored value when performing the check command.

It will also check that the system identifier is the same for both replication and standard connections, throwing an error if they are not:

error: is the streaming DSN targeting the same server of the PostgreSQL connection string?

This removes the risk of receiving WAL files from two different servers and risk to invalidate the backup.

What happens if the system identifier changes?

If the System Identifier is a unique identifier for the instance then why should it change?
Well, one use case of changing the system identifier could be when you use pg_upgrade to use a new PostgreSQL major version.
If that happens, then the Barman’s `check` command will throw an error, preventing any further backups.

-shell$ barman backup all
ERROR: Impossible to start the backup. Check the log for more details, or run 'barman check server_name'

The `check` command explicitly warns about the incongruence with the system identifier that Barman has stored in the identity file with the one that comes from the new PostgreSQL server.

-shell$ barman check all
...
systemid coherence: FAILED (the system Id of the connected PostgreSQL server changed, stored in "/var/lib/barman//identity.json")
...

You need to treat the new upgraded instance as if it were a new server to backup.

How can I retrieve the system identifier from Barman?

Via `diagnose`

The most thorough way to do it in Barman is with the `barman diagnose` command. It will print information on what the system identifier is for:

• streaming connection
• PostgreSQL standard connection
• every backup of every configured server

-shell$ barman diagnose
...
backup
-> "systemid": "6771759591265590184",
...
status
-> "postgres_systemid": "6771759591265590184",
-> "streamingsystemid": "6771759591265590184",
...

Per-server information

You can also verify the system identifier for a specific server.
Use the `barman show-server SERVER_NAME` command to retrieve it.

-shell$ barman show-server
postgres_systemid: 6771759591265590184
streaming_systemid: 6771759591265590184

Per-backup information

Similarly to servers, you can also find the system identifier for a given backup:

-shell$ barman show-backup node1 20191219T163212
Backup 20191219T163212:
Server Name :
System Id : 6771759591265590184
...

Conclusions

The last question is: Why do I need to understand all this?

As I said at the beginning of this article, Barman from the 2.10 release introduces support for the system identifier. It becomes more robust and will save us from errors when we didn’t think of, like backing up the WAL files of an upgraded server where you have the ones for the old version one.
Barman will take care of everything and it will explicitly tell us what the problem is.
This article helps us understand what barman is “telling” us in the logs and in the check command regarding the system identifier so we can investigate both on PostgreSQL and Barman side.

And remember, upgrade barman to the latest version!

Please visit  www.pgbarman.org for more information.