Starting and Stopping the Server
Pedal needs to restart its server to change a memory setting. One engineer uses systemctl, another runs pg_ctl by hand, and afterwards systemd insists PostgreSQL is "failed" while it is clearly running. There are three tools for the same job, and the rule for choosing is simple.
The rule
Start and stop it with whatever started it; stop fast, never immediate by habit.
pg_ctl is PostgreSQL's own control program. It works on a data directory and must run as the postgres OS user:
pg_ctl -D /var/lib/pgsql/17/data status
pg_ctl -D /var/lib/pgsql/17/data restart -m fast
pg_ctl -D /var/lib/pgsql/17/data reloadsystemd is how packaged installs run PostgreSQL as a service that starts at boot. The unit calls the right binaries for you:
sudo systemctl status postgresql-17 # RHEL family
sudo systemctl restart postgresql@17-main # Debian / Ubuntu
sudo systemctl reload postgresql@17-main # re-read config, no restartpg_ctlcluster is the Debian and Ubuntu wrapper that knows about several versions and clusters on one machine. pg_lsclusters lists them:
pg_lsclusters
sudo pg_ctlcluster 17 main restartIf the service manager started the server, stopping it behind systemd's back leaves systemd with a wrong picture, which is exactly what confused Pedal's engineers.
Shutdown modes (-m in pg_ctl) decide what happens to connected clients:
- smart: wait for every client to disconnect. It can wait forever.
- fast (the default): roll back open transactions, disconnect clients, write a checkpoint, stop cleanly.
- immediate: stop at once without a checkpoint. The next start runs crash recovery from the WAL. Use it only in emergencies.
Reload versus restart: a reload re-reads the configuration files and applies settings that allow it, without dropping a single connection. A restart is needed only for settings such as shared_buffers or listen_addresses.
The shortcut
Ask two questions: "What started it?" picks the tool, and "Does this change need a restart?" picks reload or restart.
What started it?
Packages and systemd, so use
systemctl(orpg_ctlcluster, which cooperates with it).
The trap is reaching for a restart when a reload would do. Every restart disconnects every client and empties PostgreSQL's own buffer cache, so the first minutes afterwards are slower. Check first; many settings, including most logging ones, apply with a reload. And if the server will not start after a change, look in the server log or journalctl -u for the unit: PostgreSQL names the bad setting in its last lines.
Drills
Answer fast — trust the rule.
Which shutdown mode is pg_ctl's default?
What happens on the next start after an immediate shutdown?
You changed log_min_duration_statement. What is the least disruptive way to apply it?
On Ubuntu, which command lists every PostgreSQL cluster and its status?
Remember
- Start and stop with whatever started it; fast is the normal shutdown.
- Reload for most settings; restart only for ones such as shared_buffers.
- Immediate shutdown means crash recovery on the next start.