How does Debian’s wrapper of postgres commands work?

What does postgres mean with “cluster”?

In Postgres' parlance a “cluster” is a postgres server. You can have multiple “clusters” on a single host, since you can have multiple postgres servers running in parallel on a host.

Debian’s “cluster” wrapping

Debian adds wrappers around all the postgres commands that extend them with a --cluster $CLUSTER parameter that allows the user to chose a specific “cluster” to run the command on.

In order to find information about clusters, the Debian postgres command wrappers look into /etc/postgresql/. They expect that directory to contain numbered directories, corresponding to postgres version. Thus

/etc/postgresql/
                9.6/
                12/
                ...

The wrappers can be told via the environment variable PG_CLUSTER_CONF_ROOT (by default set to /etc/postgresql/) where they can find their stuff.

You can use the Debian specific pg_lsclusters command to find out what Debian’s wrappers think they know about existing local “clusters”.

Working with postgres setups that don’t follow Debian’s scheme

However not all postgres servers are set up as Debian’s “cluster wrappers” expect them to be.

So f.ex. Zalando’s postgres-operator puts its postgres database under /home/postgres/pgdata/pgroot (no $PG_VERSION there!) and doesn’t care about setting up /etc/postgresql at all.

Under these circumstances Debian’s wrapped postgres commands are still able to work, since they do their work via Unix sockets.

However when using the pg... --cluster $CLUSTER invocation, Debian’s wrappers will break since they won’t find their info under /etc/postgresql/$PG_VERSION.

Where the “cluster” logic is

It’s in /usr/share/perl5/PgCommon.pm (contained in the postgresql-client-common Debian package).

In particular the get_version_clusters function there in is the switching point of it all.

Documentation

Unfortunately Debian’s “cluster wrappers” don’t seem to be documented at all. Pointers welcome.