Read PostgreSQL Cluster Status Clearly with pg_lsclusters

You will finish with a reliable way to list PostgreSQL clusters, identify the port and data directory in use, inspect one cluster, and obtain JSON for a script. The examples use pg_lsclusters from postgresql-common version 257build1.1 on this machine.

Allow about ten minutes. You need a shell and the postgresql-common package. The commands here are read-only: they do not start, stop, restart or reconfigure PostgreSQL. Most checks need no elevated privileges. Reading a cluster's recovery state may require access as root or as the cluster owner.

1. Confirm the installed command

Start by checking which executable your shell will run and which package supplied it. This avoids diagnosing a different installation from the one you intended to inspect:

$ command -v pg_lsclusters
/usr/bin/pg_lsclusters
$ dpkg-query -W -f='${Package} ${Version}\n' postgresql-common
postgresql-common 257build1.1

Ask for help if you need to confirm the option spelling. The useful switches are --no-header, --json and --start-conf, with -h, -j and -s as their short forms.

$ pg_lsclusters --help
Usage: /usr/bin/pg_lsclusters [-hjs]

Checkpoint: you have confirmed both the command path and package version. If command -v prints nothing, install or repair the package through your normal system administration process rather than guessing a path.

2. List every cluster

Run the command without positional arguments:

$ pg_lsclusters
Ver Cluster Port Status Owner    Data directory              Log file
16  main    5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log

Each row describes one cluster. Ver is the PostgreSQL major version, Cluster is its local name, and Port is the configured network port. Status normally reads online or down. The owner, data directory and log file are useful when a client cannot connect or when several versions share a host.

The output is a report, not a list of service units. A cluster can be present but down, and a port shown here can still be unreachable because of listen-address, firewall or authentication settings. Do not treat online as proof that a particular remote client can connect.

Checkpoint: record the exact version and cluster name you need, such as 16 and main. Do not confuse the cluster name with the database name. They are separate PostgreSQL concepts.

3. Narrow the report to one cluster

Supply a version to show only that version's clusters, or supply both version and cluster name:

$ pg_lsclusters 16 main
Ver Cluster Port Status Owner    Data directory              Log file
16  main    5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log

This is helpful in scripts and incident notes because the result no longer mixes similarly named clusters from different PostgreSQL versions. The version and cluster arguments are positional, so keep their order. If you specify a name that does not exist, the command reports the error and returns a non-zero status:

$ pg_lsclusters 16 does-not-exist
Error: Cluster 16 does-not-exist does not exist
$ printf 'exit status: %s\n' "$?"
exit status: 1

A missing cluster is a naming or installation problem, not a reason to start a service. Re-run the unfiltered command and compare its exact spelling before taking any administrative action.

4. Remove the header for simple shell processing

Use --no-header when another tool expects data rows only:

$ pg_lsclusters --no-header
16 main 5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log

This output is whitespace-separated, so it is convenient for a quick human check but not a strong interchange format. Paths may contain spaces on unusual installations, and column alignment is designed for display. Prefer JSON when a program must consume the fields reliably.

Do not parse the coloured terminal display by scraping escape sequences. The manpage documents green and red status lines for terminal output, while redirected output may look plain. The meaning you need is the status field, not its colour.

5. Include the configured start policy

Add --start-conf when you need to distinguish a cluster that is configured to start automatically from one that is not:

$ pg_lsclusters --start-conf
Ver Cluster Port Status      Owner    Data directory              Log file
16  main    5432 online,auto postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log

The extra value is included in the status column. In this example, online,auto says that the cluster is running and its start configuration is auto. Treat that as configuration information, not as an instruction to change the service. If you are investigating an unexpected reboot or maintenance start-up, inspect this report before editing any cluster configuration.

6. Produce JSON for a script

Use --json when you need named fields rather than display columns:

$ pg_lsclusters --json
[{"socketdir":"/var/run/postgresql","configuid":113,"config":{"max_connections":"100", ...},"running":1,"version":"16","logfile":"/var/log/postgresql/postgresql-16-main.log","start":"auto","cluster":"main","port":"5432","pgdata":"/var/lib/postgresql/16/main"}]

The real object includes configuration details from the selected cluster, so values will differ between machines. The JSON option requires Perl's JSON.pm, provided on Debian by libjson-perl. Check that dependency if the option fails:

$ dpkg-query -W -f='${Package} ${Version}\n' libjson-perl
libjson-perl 4.10000-1

For a script, validate the command status before parsing its output. Also handle an empty array: a host can have no registered clusters. Do not assume that version 16, cluster main or port 5432 exists on another machine.

7. Understand access failures without changing state

The command reads cluster metadata and some files below the data directory. The documented recovery marker is appended to the status when a recovery.conf file is found, but reading that information requires access as root or as the cluster owner. If an ordinary account cannot see it, that is an access boundary, not evidence that the cluster is down.

Retrying with elevated privileges is still a read-only action, but use it only when your operational role allows it:

$ sudo pg_lsclusters --start-conf
Ver Cluster Port Status      Owner    Data directory              Log file
16  main    5432 online,auto postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log

There is nothing to undo because these commands do not change persistent state. If a service is unexpectedly down, use the displayed owner, data directory and log path to guide a separate, authorised investigation. Do not start or stop a cluster merely to make this report look healthier.