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.