pg_ctlcluster: start/stop/restart/reload/promote a PostgreSQL cluster (postgresql-common)
pg_ctlcluster [OPTIONS] <version> <cluster> <action> [-- <pg_ctl options>]
What it does
Actions: start, stop, restart, reload, status, promote. As root, start/stop/restart are redirected to systemctl (postgresql@<version>-<cluster>) so the unit's state stays right, unless --skip-systemctl-redirect.
Options you will use
-m, --mode=smart|fast|immediate- shutdown mode for stop/restart: smart waits for clients, fast (default) disconnects them, immediate exits without a checkpoint (crash recovery on next start).
--skip-systemctl-redirect- do not hand over to systemctl (the unit itself uses this).
-f, --force- with stop: try fast, then immediate.
-o, --options=OPTIONS- pass options to postgres.
Examples
$ sudo pg_ctlcluster 18 main reloadSIGHUP: re-read the config
$ sudo pg_ctlcluster 18 replica promoteend recovery: the replica becomes a primary
$ sudo -u postgres pg_ctlcluster 18 main stop -m immediatestop at once (crash recovery on start)
Gotchas
- As root,
pg_ctlcluster 18 main restartandsystemctl restart postgresql@18-mainare the same thing. Calling pg_ctl directly bypasses the unit, and systemd then shows the wrong state. - reload re-reads postgresql.conf and pg_hba.conf without disconnecting anyone; settings marked "postmaster" in pg_settings.context still need a restart.
Taught in
Try pg_ctlcluster in a real terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.