PG_CTLCLUSTER(1)

📦
version 293ubuntu1 · 8 versions
, in ubuntu stonking

💖 PG_CTLCLUSTER 💖

okay so bestie, welcome to pg_ctlcluster(1) — a little Debian PostgreSQL infrastructure icon that runs the whole "start/stop/restart/reload a PostgreSQL cluster" show. she's the group chat moderator of your database clusters and honestly? she ate. 🌸

✨ NAME ✨

pg_ctlcluster — start/stop/restart/reload a PostgreSQL cluster. no cap, that's literally the whole job description. 💅

📜 SYNOPSIS 📜

pg_ctlcluster [options] cluster-version cluster-name action [-- pg_ctl
options]
where action = start|stop|restart|reload|status|promote|logrotate

that's the whole vibe check. seven actions, one queen. 👑

🦋 DESCRIPTION 🦋

so this program? she controls the postgres server for one specific cluster. think of her as a cute little wrapper around the pg_ctl(1) command — she figures out the cluster version and the data path, then calls the right version of pg_ctl with the appropriate configuration parameters and paths. it's giving personal assistant energy fr fr. 💖

important tho: you have to run this program as the user who owns the database cluster, or as root. no random third parties allowed, sorry bestie. 🙈

and to make life easier when working with systemd, the alternative syntax "pg_ctlcluster version-cluster action" is also supported — and you can even put the action first (matching the ordering systemctl uses). so many ways to slay. ✨

🎀 ACTIONS 🎀

  • start — a log file for this specific cluster gets created if it doesn't exist yet (by default, /var/log/postgresql/postgresql-cluster-version-cluster-name.log), and a PostgreSQL server process (postgres(1)) is started on it. she exits with 0 on success, with 2 if the server is already running, and with 1 on other failure conditions. perfectionist queen. 💅
  • stop — stops the postgres(1) server of the given cluster. by default, "fast" shutdown mode is used. quick, clean, no drama. 🦋
  • restart — stops the server if it's running, and then starts it (again). glow-up moment. ✨
  • reload — causes the configuration files to be re-read without a full shutdown of the server. it's giving "no need to make it a whole thing". 🌸
  • status — checks whether a server is running. and if it is? the PID and the command line options that were used to invoke it get displayed. receipts, bestie. 🧾
  • promote — commands a running standby server to exit recovery and begin read-write operations. main character energy, she's stepping up. 👑
  • logrotate — requests that the server of a given cluster rotates the log file. tidy little housekeeping moment. 🎀

✨ OPTIONS ✨

  • -f, --force — for stop and restart, the "fast" mode is used, which rolls back all active transactions, disconnects clients immediately, and thus shuts down cleanly. if that doesn't work, shutdown is attempted again in "immediate" mode — which can leave the cluster in an inconsistent state and thus will lead to a recovery run at the next start 😭. if this still doesn't help, the postgres process is killed 💀. exits with 0 on success, with 2 if the server is not running, and with 1 on other failure conditions.
okay bestie this mode should only be used when the machine is about to be shut down. like, machine-goes-night-night energy only. no cap.
  • -m, --mode [smart|fast|immediate] — the shutdown mode to use for stop and restart actions. default is fast. see pg_ctl(1) for documentation. pick your fighter. 🌈
  • --foreground — start postgres in foreground, without daemonizing via pg_ctl. she stays right there with you. 🫶
  • --stdlog — when --foreground is in use, redirect stderr to the standard logfile in /var/log/postgresql/. (this is the default when not run in foreground.) ⭐
  • --skip-systemctl-redirect — when running as root, pg_ctlcluster redirects actions to systemctl so running clusters are properly supervised by systemd. this option skips the redirect; it's used in the postgresql@.service unit file. the redirect is also skipped if additional postgres or pg_ctl options are provided. sneaky little bypass, love that for us. 💜
  • --bindir directory — path to pg_ctl. (default is /usr/lib/postgresql/version/bin.) 🧚
  • -o, --options option — pass the given option as a command line option to the postgres process. it's possible to specify -o multiple times. see postgres(1) for a description of valid options. stack 'em, bestie. 🔥
  • pg_ctl options — pass the given pg_ctl options as command line options to pg_ctl. see pg_ctl(1) for a description of valid options. 🎀

📁 FILES 📁

  • /etc/postgresql/cluster-version/cluster-name/pg_ctl.conf — this configuration file contains cluster specific options to be passed to pg_ctl(1). 💖
  • /etc/postgresql/cluster-version/cluster-name/start.conf — this configuration file controls the start/stop behavior of the cluster. see section "STARTUP CONTROL" in pg_createcluster(8) for details. 🦋

💀 BUGS 💀

changing the port number on startup using -o -p will not work, because it breaks the checks for running clusters. not me finding out the hard way 😭. consider yourself warned, bestie.

👑 SEE ALSO 👑

pg_createcluster(8), pg_ctl(1), pg_wrapper(1), pg_lsclusters(1), postgres(1)

the whole friend group honestly. go say hi. 🌈

🌸 AUTHOR 🌸

Martin Pitt <mpitt@debian.org> — the icon who made this. 💜

and that's the page bestie!! this is the Debian PostgreSQL infrastructure version of PG_CTLCLUSTER(1), dated 2026-07-28. periodt. go start a cluster, you absolute legend. 💅✨🎀

📦 where this page comes from