Service management, and stopping PostgreSQL safely · PostgreSQL

Stopping a database is not one operation. PostgreSQL offers three shutdown modes that differ in how much they are willing to wait for and what state they leave behind, and the difference between the gentlest and the harshest is the difference between a clean restart and a recovery.

Most operators never choose a mode. It is chosen for them by the systemd unit, by a container runtime’s stop signal, or by whoever decided a shutdown was taking too long.

The three modes

Mode	Signal	Waits for	Next start
Smart	`SIGTERM`	Every client to disconnect voluntarily	Clean
Fast	`SIGINT`	In-flight transactions to roll back	Clean
Immediate	`SIGQUIT`	Nothing	Crash recovery

Smart is the polite one. The server stops accepting new connections and then waits — indefinitely by default — for existing clients to disconnect on their own. An application holding an idle connection pool will hold the shutdown open forever, which is why smart mode is rarely what an operator wants and is no longer the default for pg_ctl.

Fast is the operational default and the right one in nearly every case. It disconnects clients, rolls back their in-flight transactions, writes a shutdown checkpoint, and exits. Committed data is durable, uncommitted work is discarded, and the next start is clean.

Immediate does not roll anything back and does not checkpoint. It signals every process to exit at once. Committed transactions are still safe — that is what the write-ahead log guarantees — but the data files are left in an inconsistent state, so the next start performs crash recovery.

flowchart TD
    S["Shutdown requested"] --> M{"Which mode?"}
    M -- "smart / SIGTERM" --> W["Refuse new connections\nwait for clients to leave"]
    M -- "fast / SIGINT" --> D["Disconnect clients\nroll back open transactions"]
    M -- "immediate / SIGQUIT" --> K["Signal all processes\nto exit at once"]
    W --> C["Shutdown checkpoint"]
    D --> C
    C --> CS["State: shut down\nnext start is clean"]
    K --> IS["State: in production\nnext start replays WAL"]

Why immediate is not merely slower

The cost of an immediate shutdown is not paid at shutdown. It is paid at the next start, and it is paid in time that is difficult to predict.

Crash recovery replays the write-ahead log from the last checkpoint to the end. How long that takes depends on how much WAL accumulated since that checkpoint, which depends on the write rate and the checkpoint configuration. On a busy cluster with max_wal_size set generously — which is what Part XII will recommend for other good reasons — this can be minutes.

Those minutes are downtime during which the server is not accepting connections, and it reports why:

FATAL:  the database system is starting up

An operator who chose immediate mode to make the shutdown finish quickly has traded a bounded wait for an unbounded one, at the point where the service is already down.

Escalating to immediate because the shutdown is taking too long

The sequence is familiar. A fast shutdown is issued during a change window. It does not complete within a minute. The window is tight, so somebody sends SIGQUIT, or kill -9, or restarts the host.

What was the fast shutdown waiting for? Almost always one of two things: a long-running transaction that has to roll back, or a checkpoint writing out a large volume of dirty buffers. Both are doing necessary work, and both are work that does not disappear — it is deferred to the next start, where it happens as recovery instead, with no client connections allowed while it runs.

So the escalation does not save the time. It moves the time from a window where the service was going down anyway into a window where everyone is waiting for it to come up, and it removes the option of cancelling the shutdown and trying again later.

The correct response is to find out what the shutdown is waiting for before escalating. pg_stat_activity still answers during a smart shutdown, and the server log reports what it is doing during a fast one. If the answer is a checkpoint, waiting is genuinely the fastest path.

What each tool actually sends

# pg_ctl: the mode is explicit. Fast is the default from PostgreSQL 9.5.
pg_ctl -D "$PGDATA" stop -m fast
pg_ctl -D "$PGDATA" stop -m smart
pg_ctl -D "$PGDATA" stop -m immediate

# Debian wrapper: same modes, addressed by version and cluster name
pg_ctlcluster 18 main stop --mode fast

# systemd: the unit decides, and the unit is where to look
systemctl stop postgresql@18-main     # Debian
systemctl stop postgresql-18          # Red Hat

The systemd case is the one worth inspecting rather than assuming, because the unit encodes both the signal and a timeout:

systemctl cat postgresql@18-main 2>/dev/null | grep -iE 'KillSignal|TimeoutStopSec|ExecStop'
systemctl show postgresql-18 -p TimeoutStopUSec -p KillSignal 2>/dev/null

TimeoutStopSec is the parameter that matters most and is least often examined. When it expires, systemd escalates to SIGKILL — which is harsher than immediate mode, because it does not even let the postmaster signal its children in an orderly way. The result is the same crash recovery, arrived at without anyone choosing it.

Verifying that a shutdown was clean

Do not assume. The control file records the answer, and it can be read while the cluster is stopped.

Read-only / Safethe cluster state recorded in pg_control— 'shut down' means clean. 'in production' on a stopped cluster means it did not shut down cleanly.

$ pg_controldata $PGDATA | grep -i 'cluster state'

Database cluster state:               in production

The states worth recognising:

State	Means
`in production`	Running — or stopped without a clean shutdown
`shut down`	Cleanly shut down; next start will not recover
`shut down in recovery`	A standby, cleanly stopped
`in archive recovery`	Replaying WAL, as a standby or during PITR
`starting up`	Mid-startup

Reading in production on a cluster you believe is stopped is the signal that the next start will perform recovery. That is worth knowing before you start it, because it tells you the startup will take longer than usual and that the delay is expected rather than a fault.

The server log states it plainly at the next start. This is a real capture: a PostgreSQL 18.6 cluster holding 200,000 rows was sent SIGQUIT and then restarted.

Read-only / Safethe log of an actual crash recovery— Captured 2026-08-27 by sending SIGQUIT to a live cluster and restarting it.

$ docker logs rbpg-crash

LOG:  database system was interrupted; last known up at 2026-08-27 17:31:08 UTC
LOG:  database system was not properly shut down; automatic recovery in progress
LOG:  redo starts at 0/1761990
LOG:  invalid record length at 0/4A0E7D8: expected at least 24, got 0
LOG:  redo done at 0/4A0E390 system usage: CPU: user: 0.04 s, system: 0.01 s, elapsed: 0.05 s
LOG:  checkpoint starting: end-of-recovery immediate wait
LOG:  checkpoint complete: wrote 5915 buffers (36.1%), ... distance=51891 kB
LOG:  database system is ready to accept connections

Read that sequence as the whole story of a recovery: it was interrupted, it knew it, it replayed from 0/1761990 to 0/4A0E390, it checkpointed, and it opened for business. All 200,000 rows were present afterwards, because every one of them had been committed.

A restart procedure should capture these lines, because their absence is how you confirm a shutdown really was clean.

Why committed data survives an immediate shutdown

An immediate shutdown discards work in progress and leaves data files inconsistent, yet no committed transaction is lost. That is not luck; it is the entire purpose of write-ahead logging, and it is worth understanding here because it explains why crash recovery is safe rather than merely usual.

Before any data page is modified, a record describing the modification is written to the write-ahead log, and before a COMMIT returns to the client, that log record is flushed to durable storage. The data page itself may still be sitting dirty in shared buffers, unwritten. The guarantee is about the log, not the pages.

So at the moment of an immediate shutdown there are two categories of change. Changes whose WAL records reached disk, which includes every committed transaction. And changes that existed only in memory, which are gone.

Recovery replays the log forward from the last checkpoint, reapplying every logged change to the data pages. Committed transactions are reconstructed. Transactions that were in flight are found to have no commit record and are treated as never having happened. The result is a consistent state that includes exactly the committed work.

The cost is the replay time, which is why the last checkpoint’s position matters so much: recovery starts there, so a cluster that checkpointed recently has less to replay. Part XII makes this the central trade of checkpoint configuration.

Starting, reloading and restarting

# Reload configuration without disconnecting anyone. Applies sighup parameters.
psql -U postgres -c 'SELECT pg_reload_conf()'
# or
pg_ctl -D "$PGDATA" reload
systemctl reload postgresql@18-main

# Restart, which is a stop and a start with all the above applying to the stop
pg_ctl -D "$PGDATA" restart -m fast

pg_reload_conf() is worth preferring over the packaging-specific alternatives in runbooks, for the reason the previous lesson gave: it works identically on every layout and does not depend on a unit name. It sends the same SIGHUP the other forms do.

A reload never disconnects a client and never interrupts a query. If a procedure’s only change is to sighup-context parameters, it needs no outage at all — which is a conversation worth having with a change board that treats every database change as a restart.

Production discipline

Use fast mode. Smart waits indefinitely for clients that may never leave; immediate defers the work to the next startup where it costs more.
Never escalate a slow shutdown to immediate without knowing what it is waiting for. The work does not disappear; it moves to recovery, where clients are locked out while it runs.
Compare TimeoutStopSec against a timed shutdown of your largest cluster. A timeout shorter than the shutdown checkpoint converts every planned restart into an unintended crash recovery.
Read pg_controldata before starting a cluster you found stopped. in production means recovery is coming and the startup will take longer.
Prefer pg_reload_conf() in runbooks. It is packaging-independent and it makes clear that a reload is not a restart.

Cross-course references

Linux for Production Sysadmins — Part VII (systemd) covers unit files, TimeoutStopSec and the escalation to SIGKILL that this lesson warns about, and Part VI (Processes) covers the signals themselves.
Docker & Containers — Part VI (Container lifecycle) covers docker stop, its default grace period and which signal it sends, which is the container form of exactly this question.
Kubernetes for Production Sysadmins — Part X (Termination) covers terminationGracePeriodSeconds, which is the same timeout problem again with a different name.