Shutdown modes and their recovery consequences · PostgreSQL

Three modes, and the one that sounds most considerate is the one most likely to cause an outage.

Read-only / Safewhat PostgreSQL says about them— Captured on 18.6.

$ pg_ctl --help

Shutdown modes are:
smart       quit after all clients have disconnected
fast        quit directly, with proper shutdown (default)
immediate   quit without complete shutdown; will lead to recovery on restart

Mode	Signal	Existing sessions	Clean shutdown?	Recovery on restart?
`smart`	`SIGTERM`	Waits for them to leave	Yes	No
`fast`	`SIGINT`	Disconnected, transactions rolled back	Yes	No
`immediate`	`SIGQUIT`	Killed	No	Yes

Fast: the default and usually the answer

Configuration changefast shutdown with a session holding an uncommitted INSERT— Captured on 18.6. A session had run BEGIN, an INSERT of 10 rows, and was sleeping.

$ pg_ctl -D $PGDATA -m fast -w stop

waiting for server to shut down....done

elapsed: 119 ms

-- on restart:
LOG:  database system was shut down at 2026-08-27 21:13:23 UTC
LOG:  database system is ready to accept connections

-- the uncommitted rows:
SELECT count(*) FROM crashtest WHERE id > 2000000;  ->  0

119 milliseconds. The session was disconnected, its uncommitted work discarded — correctly, since it was never committed — and the shutdown completed cleanly, so the restart needed no recovery.

fast is the right choice for planned maintenance, deployments, failovers and almost everything else.

Smart: the trap

Service impact possiblesmart shutdown with one ordinary idle session connected— Real output from 18.6. The session was idle — not even inside a transaction.

$ pg_ctl -D $PGDATA -m smart -w -t 10 stop

pg_ctl: server does not shut down
HINT: The "-m fast" option immediately disconnects sessions rather than
waiting for session-initiated disconnection.

elapsed: 10 s, and the server was still running

Service impact possibleand, while that shutdown was pending— Real error from 18.6, from a new connection attempt during the smart shutdown.

$ psql -U postgres -c "SELECT 'still up'"

psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432"
failed: FATAL:  the database system is shutting down

Smart shutdown can make a cluster unavailable without ever completing

Read those two captures together, because the combination is the problem:

It waits indefinitely for existing clients to disconnect of their own accord. One idle session — not in a transaction, not doing anything — was enough to block it for the full timeout.

It refuses new connections while it waits. The cluster is not serving anyone, and it is not shutting down either.

On a production system behind a connection pooler, the pooler holds its server connections open by design. They will never disconnect voluntarily. A smart shutdown against that cluster waits forever while every new request is refused.

This is not a hypothetical failure mode; it is what smart mode does, and it is why fast is the default.

The narrow case where smart is right: a batch-only cluster with a known, finite set of jobs that will end on their own, where you want to let them finish. Even then, set a timeout and a fallback:

pg_ctl -D "$PGDATA" -m smart -w -t 300 stop || pg_ctl -D "$PGDATA" -m fast -w stop

Immediate: a deliberate crash

Destructiveimmediate shutdown, and the restart it produces— Captured on 18.6. Note that the restart log is identical in form to the SIGKILL case.

$ pg_ctl -D $PGDATA -m immediate -w stop

waiting for server to shut down....done

-- on restart:
LOG:  database system was interrupted; last known up at 2026-08-27 21:14:24 UTC
LOG:  database system was not properly shut down; automatic recovery in progress
LOG:  redo is not required
LOG:  checkpoint complete: wrote 0 buffers (0.0%) ... distance=0 kB, estimate=0 kB
LOG:  database system is ready to accept connections

The was interrupted and not properly shut down lines are identical to the SIGKILL case in lesson XII-06. Immediate shutdown is a crash that you asked for.

redo is not required appears here only because a checkpoint had completed moments earlier and nothing had been written since. On a busy cluster the same command produces a full redo. The mode does not choose how much recovery is needed; the distance since the last checkpoint does.

Legitimate uses: a hung cluster that will not respond to fast, and a cluster you are about to discard. Not legitimate: as a faster way to stop a healthy server, because the time saved on the way down is paid back with interest on the way up.

Systemd, and the reboot you did not think about

A host reboot sends SIGTERM to services, which for PostgreSQL is smart mode. With a pooler holding connections, that stops nothing; systemd then waits for TimeoutStopSec — 90 seconds by default — and sends SIGKILL, which is an unclean crash.

So a routine reboot produces a 90-second hang followed by a crash, on a cluster that would have stopped cleanly in 119 milliseconds.

The packaged units on major distributions handle this, and it is worth confirming rather than assuming:

systemctl cat postgresql@18-main | grep -E 'KillSignal|TimeoutStopSec|ExecStop'

What you want to see is either an ExecStop invoking pg_ctl with -m fast, or KillSignal=SIGINT, which is the signal fast mode uses.

[Service]
KillSignal=SIGINT
TimeoutStopSec=300
KillMode=mixed

TimeoutStopSec should exceed the time a fast shutdown genuinely takes on your cluster — the shutdown checkpoint has to write every dirty buffer, which on a large shared_buffers is not instant.

Shutting down deliberately, in order

-- 1. see what will be interrupted
SELECT pid, usename, application_name, state,
       now() - xact_start AS xact_age, left(query, 60) AS query
  FROM pg_stat_activity
 WHERE backend_type = 'client backend' AND state <> 'idle';

-- 2. stop new work arriving, if you have that control
--    (pooler pause, load balancer drain, or ALTER SYSTEM SET
--     max_connections is NOT the tool — it needs a restart)

-- 3. checkpoint first, so the shutdown checkpoint is small
CHECKPOINT;

# 4. then stop
pg_ctl -D "$PGDATA" -m fast -w -t 300 stop

# 5. confirm it was clean
pg_controldata "$PGDATA" | grep 'cluster state'
#   Database cluster state:               shut down

Step 3 matters more than it looks. A fast shutdown performs a shutdown checkpoint that must write every dirty buffer, and on a large pool that can take minutes. Issuing CHECKPOINT beforehand does most of that work while the cluster is still serving traffic, so the shutdown itself has little left to do.

Step 5 is the one people skip. shut down in the control file is the proof; anything else means the next start will run recovery.

Why a shutdown checkpoint can take a long time, and what to watch

A clean shutdown ends with a shutdown checkpoint, which differs from an ordinary one in a way that matters during a maintenance window.

An ordinary checkpoint is spread across checkpoint_completion_target × checkpoint_timeout — 270 seconds on defaults — deliberately pacing its writes so as not to disturb the workload.

A shutdown checkpoint is not spread. There is no workload left to protect, so it writes everything as fast as the storage allows. On a 64 GB shared_buffers that is potentially tens of gigabytes of dirty pages issued at once.

Three practical consequences.

A large shared_buffers makes shutdowns slower, and the time is proportional to how dirty the pool is rather than to its size. A read-mostly cluster with a huge pool shuts down quickly; a write-heavy one with the same pool does not.

CHECKPOINT immediately beforehand is the mitigation, and it is free in the sense that the work has to happen either way — the choice is whether it happens while the cluster is serving or while it is unavailable.

Watch it rather than guessing:

-- before deciding, see how much is dirty
SELECT count(*) FILTER (WHERE isdirty) AS dirty_buffers,
       pg_size_pretty(count(*) FILTER (WHERE isdirty) * 8192::bigint) AS dirty_size
  FROM pg_buffercache;

or more cheaply, from lesson XI-02’s summary function:

SELECT buffers_dirty, buffers_used FROM pg_buffercache_summary();

A cluster with 30 GB dirty is a cluster whose shutdown will take as long as writing 30 GB takes on its storage, and that is a number you can compute in advance rather than discover with a maintenance window running out.

What to take from this

fast is the default and the right answer almost always. Measured at 119 ms.
smart waits indefinitely and refuses new connections. One idle session blocked it for its full timeout.
immediate is a deliberate crash. The restart log is identical to a SIGKILL.
A host reboot sends SIGTERM, which is smart mode. Check your systemd unit uses -m fast or KillSignal=SIGINT.
CHECKPOINT before stopping, so the shutdown checkpoint is small.
Confirm with pg_controldata: Database cluster state: shut down.

Cross-course references

Linux for Production Sysadmins — Part VII (systemd) covers TimeoutStopSec and what expires into a kill, which is how a smart shutdown quietly becomes a crash.
Docker & Containers — Part VI (Container lifecycle) covers docker stop’s grace period, which is the same trap with a different default.
Kubernetes for Production Sysadmins — Part X (Pod termination and signals) covers terminationGracePeriodSeconds, which is where this goes wrong on a cluster nobody tuned.