Control a Debian PostgreSQL Cluster with pg_ctlcluster

pg_ctlcluster is Debian's wrapper for starting, stopping and reloading a named PostgreSQL cluster. This guide keeps ordinary reloads separate from disruptive stops and restarts, the distinction that saves you from an unplanned outage. Allow about ten minutes for a routine check, or longer if you need to investigate a failed start.

The examples match postgresql-common version 257build1.1 and the installed pg_ctlcluster(1) manual. You need the cluster version and name, the postgresql-common package, and either the database cluster owner or root. On this system the example cluster is version 16, named main; substitute your own values after checking them, and do not guess a cluster name from a directory path.

1. Find the exact cluster identity

Use pg_lsclusters to list the clusters managed by Debian's PostgreSQL tooling. This is a read-only command and normally needs no elevated privileges:

$ 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

The two values pg_ctlcluster needs are the first two columns: 16 and main. The main form is pg_ctlcluster VERSION NAME ACTION. Debian also accepts pg_ctlcluster VERSION-NAME ACTION, and an action-first form, but the three-part form reads easiest in notes and scripts.

2. Check status as the cluster owner

Run status as the owner shown by pg_lsclusters, or as root. This example uses the owner and does not change the server:

$ sudo -u postgres pg_ctlcluster 16 main status
pg_ctl: server is running (PID: 3097710)
/usr/lib/postgresql/16/bin/postgres "-D" "/var/lib/postgresql/16/main" "-c" "config_file=/etc/postgresql/16/main/postgresql.conf"

The PID and command line will differ. Exit status 0 means the server is running; the command returns 2 when it is not running, and 1 for another failure. If you run it as an unrelated unprivileged user, the installed command rejects the request before it can report the cluster state. That is a permissions problem, not proof PostgreSQL is stopped.

3. Start a stopped cluster

Starting a service changes system state, so confirm the version, name and intended host first. Then run the start action as root or the owner:

$ sudo pg_ctlcluster 16 main start
$ sudo -u postgres pg_ctlcluster 16 main status
pg_ctl: server is running (PID: 12345)

On a successful start, the command exits 0. A start against an already-running cluster exits 2. A normal start creates the cluster log if it does not exist; the default path is /var/log/postgresql/postgresql-16-main.log, so check the path printed by pg_lsclusters on your machine if the start fails:

$ sudo tail -n 40 /var/log/postgresql/postgresql-16-main.log

On a systemd-managed installation, root invocation is normally redirected to systemctl so the service stays supervised. That is expected behaviour. Do not add --skip-systemctl-redirect merely to make the output look different; the option is meant for the PostgreSQL systemd unit and other specialised cases.

4. Reload configuration without a full restart

Use reload when PostgreSQL supports applying the configuration change without stopping the server:

$ sudo pg_ctlcluster 16 main reload
$ sudo -u postgres pg_ctlcluster 16 main status
pg_ctl: server is running (PID: 12345)

A reload asks PostgreSQL to re-read its configuration. It does not guarantee every setting can change this way. Check the PostgreSQL log and the relevant setting's documentation when a change appears not to take effect. If the change needs a restart, schedule the interruption and use restart deliberately.

5. Stop or restart with an explicit shutdown mode

Stopping or restarting disconnects clients, so warn users and check the workload first. The default mode is fast: active transactions roll back and clients disconnect so the server shuts down cleanly.

$ sudo pg_ctlcluster --mode fast 16 main stop
$ sudo -u postgres pg_ctlcluster 16 main status
pg_ctl: no server running

For a planned configuration change, a restart performs the same stop and then starts the cluster again:

$ sudo pg_ctlcluster --mode fast 16 main restart
$ sudo -u postgres pg_ctlcluster 16 main status

• --mode smart waits for clients to disconnect.
• --mode immediate stops without a clean shutdown and can require recovery at the next start. Do not use it as a routine shortcut.
• --force escalates from fast to immediate, then kills the PostgreSQL process if necessary. The manual says it should only be used when the machine is about to be shut down.

6. Promote a running standby only with a failover decision

The promote action tells a running standby to leave recovery and begin read-write operation:

$ sudo pg_ctlcluster 16 standby promote
$ sudo -u postgres pg_ctlcluster 16 standby status

Replace standby with the real cluster name. Promotion changes the database role and is not an ordinary health check. Confirm the failover plan, replication state and application routing are ready before running it.

7. Diagnose the common traps

If an action fails, rerun pg_lsclusters and check the matching log rather than changing ports or paths at random. The manual warns that changing the port at startup with -o -p breaks the checks for running clusters. Use the configured cluster port and make a planned configuration change through PostgreSQL's normal configuration workflow.

Options after -- are passed to pg_ctl. The -o or --options option passes an option to the postgres process, and can be repeated. Keep these advanced options out of routine start and stop commands unless the PostgreSQL documentation and your service configuration require them; extra PostgreSQL or pg_ctl options also affect the systemd redirect behaviour.