Server shutdown modes

For DBAs and operators

Smart — wait for the users

pg_ctl stop -m smart sends SIGTERM to the postmaster. PostgreSQL stops accepting ordinary new connections but remains in its running/hot-standby state while existing client sessions finish. Only after the regular sessions have gone does the postmaster advance into the shutdown states.

Fast — stop sessions, then shut down cleanly

pg_ctl stop -m fast sends SIGINT. This is the default pg_ctl stop mode. PostgreSQL refuses new sessions and tells existing server processes to terminate; client backends abort active transactions and exit promptly. The postmaster waits for the relevant children before moving on to the clean database-shutdown phase.

The clean-shutdown tail

For both smart and fast shutdown, once backends are out of the way the postmaster reaches PM_WAIT_XLOG_SHUTDOWN and asks the checkpointer to perform the shutdown-WAL work. In checkpointer.c, SIGINT sets ShutdownXLOGPending, then ShutdownXLOG() performs the shutdown checkpoint/restartpoint work and notifies the postmaster with PMSIGNAL_XLOG_IS_SHUTDOWN. The state machine then waits for remaining WAL archival/sender work, I/O workers and the checkpointer before the postmaster exits.

Immediate — deliberately unclean

pg_ctl stop -m immediate sends SIGQUIT. The postmaster relays an immediate-abort signal to its children and does not run normal database shutdown processing. PostgreSQL waits for the children to terminate; a child still alive after 5 seconds can receive SIGKILL. The next start therefore follows the crash-recovery path and replays WAL.

Durability versus consistency

Immediate shutdown is designed to recover to a consistent database state through WAL redo; it is not a normal way to "corrupt" a healthy PostgreSQL cluster. However, durability still follows each transaction's configured commit guarantees. With the usual synchronous_commit = on, a commit is acknowledged only after the required local WAL flush. Modes that intentionally acknowledge before durable flush can lose a small window of recently acknowledged work after a crash/immediate stop.

Operational commands

pg_ctl stop -D "$PGDATA" -m smart
pg_ctl stop -D "$PGDATA" -m fast       # pg_ctl default
pg_ctl stop -D "$PGDATA" -m immediate  # emergencies

# -w (the default for stop) waits until postmaster.pid disappears
pg_ctl stop -D "$PGDATA" -m fast -w

PostgreSQL 18 source trail: postmaster.c defines SmartShutdown, FastShutdown, ImmediateShutdown and the shutdown state machine. checkpointer.c documents the normal shutdown checkpoint path. See also PostgreSQL 18: Shutting Down the Server and pg_ctl.