skip to content

In PostgreSQL, what do pg_ctl stop's smart, fast and immediate modes do, which is the default, and when would you use each?

level: middleimportance: must knowfreq 62%

answer

  1. three signals to one process
  2. who waits for whom
  3. checkpoint at the end, or not
  4. the default rolls back

basics

~20 s

Smart refuses new connections and waits for every session to end; fast, the default, rolls back open transactions, disconnects everyone and writes a shutdown checkpoint; immediate kills all processes without a checkpoint, so the next start runs crash recovery.

solid answer

~40 s

`pg_ctl stop -m` picks a signal for the postmaster. **Smart** (`SIGTERM`) refuses new connections but waits until every existing session disconnects on its own, idle ones included, so it can wait forever. **Fast** (`SIGINT`, the default) refuses new connections, rolls back active transactions, terminates sessions, writes a shutdown checkpoint and lets walsenders ship the remaining WAL to connected standbys, so the next start needs no recovery. **Immediate** (`SIGQUIT`) stops every child process at once (with `SIGKILL` after 5 seconds) and skips the checkpoint, so the next start replays WAL as crash recovery. Use fast for planned maintenance, smart only when you control every client, and immediate only in an emergency. Never `kill -9` the postmaster.

code

bash · 11 lines
bash
# default (fast): SIGINT, roll back, disconnect, shutdown checkpoint
pg_ctl stop -D /srv/pg/inventory

# smart: SIGTERM, refuse new connections, wait for sessions to end
pg_ctl stop -D /srv/pg/inventory -m smart

# immediate: SIGQUIT, no checkpoint, crash recovery at next start
pg_ctl stop -D /srv/pg/inventory -m immediate

# fast, but allow 5 minutes for a large shutdown checkpoint
pg_ctl stop -D /srv/pg/inventory -m fast -t 300

go deeper

for a junior

Remember the three names and that fast is the default: smart waits for sessions, fast rolls back and disconnects them, immediate stops everything and needs recovery at the next start.

for a middle

Map each mode to its signal and explain what fast does step by step: refuse connections, roll back, shutdown checkpoint, ship WAL to standbys, remove postmaster.pid.

for a senior

Show the operational judgment: why smart stalls on pooled idle connections, how to escalate a shutdown in progress, why kill -9 is dangerous, and what an immediate stop costs at the next start.

for a principal

Weigh a fast stop's checkpoint time against an immediate stop's recovery time in runbooks, and set expectations for how long a maintenance restart of a write-heavy cluster really takes.

## Three modes, three signals Every way of stopping a PostgreSQL server comes down to sending a signal to the supervisor process, the **postmaster**, whose PID is the first line of `postmaster.pid` in the data directory. `pg_ctl stop -m <mode>` sends the right one and then waits for the server to remove that file. | Mode | Signal | New connections | Existing sessions | Shutdown checkpoint | Next start | |---|---|---|---|---|---| | `smart` | `SIGTERM` | refused | allowed to finish; waits until all disconnect | yes | normal | | `fast` (default) | `SIGINT` | refused | active transactions rolled back, sessions terminated | yes | normal | | `immediate` | `SIGQUIT` | refused | processes stopped at once, no cleanup | no | crash recovery | ## Smart shutdown After `SIGTERM`, the postmaster logs `received smart shutdown request` and stops accepting ordinary client connections, but every existing session keeps working until it disconnects by itself. **Idle sessions count**: a connection pool that holds idle connections open will keep a smart shutdown waiting indefinitely. Once the last session is gone, the server shuts down exactly like a fast shutdown, including the checkpoint. On a hot standby, recovery and streaming replication carry on until all regular sessions have ended. ## Fast shutdown, the default After `SIGINT`, the server: 1. Refuses new connections and logs `aborting any active transactions`. 2. Sends `SIGTERM` to its child processes; each backend rolls back its open transaction and exits. Rolling back is cheap in PostgreSQL: the aborted transaction's row versions simply remain as dead tuples for VACUUM to clear later. 3. Has the checkpointer write a **shutdown checkpoint**, flushing every dirty buffer and recording a checkpoint that marks the cluster as cleanly shut down. 4. Waits for walsenders to transfer outstanding WAL to the standbys that are still connected. 5. Logs `database system is shut down` and removes `postmaster.pid`. Because of step 3, the next start needs no recovery. ## Immediate shutdown After `SIGQUIT`, the postmaster forwards `SIGQUIT` to every child, sends `SIGKILL` to any that have not exited within **5 seconds**, and exits without normal shutdown processing. No checkpoint is written, so the next start finds a cluster that was never shut down and replays WAL from the last checkpoint. That is crash recovery, and it has side effects of an unclean stop: - transactions acknowledged as committed under the default `synchronous_commit = on` survive, because their WAL was already on disk; - **unlogged tables** are truncated at the next start; - the cumulative statistics counters in the `pg_stat_*` views are reset. The manual recommends it only in emergencies. ## Choosing a mode - **Planned maintenance or a restart**: fast. It is predictable and leaves a clean cluster. - **Letting running work finish**: smart, but only once you have drained or stopped the application, otherwise idle connections stall it. - **The server must stop now** (a fast shutdown is stuck, or storage is failing): immediate, accepting crash-recovery time at the next start. - **Never `SIGKILL` the postmaster.** A killed postmaster cannot relay the signal to its children, does not release shared memory and semaphores, and can leave orphaned backends that you must kill by hand before the server will start again. ## What the log shows The server log makes the mode visible after the fact: - `received smart shutdown request`, `received fast shutdown request` or `received immediate shutdown request` records which signal arrived; - `checkpoint starting: shutdown immediate` followed by `database system is shut down` marks a clean finish; - at the next start, `database system was shut down at …` follows a clean stop, while `database system was not properly shut down; automatic recovery in progress` follows an immediate one. ## Escalation and timeouts A stronger request upgrades a shutdown already in progress: a waiting smart shutdown becomes fast when you run `pg_ctl stop -m fast`, and either becomes immediate with `-m immediate`. A weaker or repeated request is ignored. `pg_ctl` waits up to 60 seconds by default (`-t`, or `PGCTLTIMEOUT`); when it gives up it exits non-zero, but the shutdown keeps going. A fast shutdown can itself take a while when there are many dirty buffers to write, so a manual `CHECKPOINT` shortly before a planned stop shortens it. Without `pg_ctl`, the same signals can be sent with `kill`, for example `kill -INT "$(head -1 /srv/pg/inventory/postmaster.pid)"` for a fast shutdown.

  • A smart shutdown is already waiting. Can you turn it into a fast one without starting over?
    Yes. Run `pg_ctl stop -m fast` (or send `SIGINT`): the postmaster upgrades a shutdown in progress to a stronger mode, rolls back open transactions, disconnects the waiting sessions and finishes with a shutdown checkpoint. It ignores a request that is weaker than or equal to the one in progress.
  • Why is kill -9 on the postmaster worse than an immediate shutdown?
    `SIGKILL` cannot be caught, so the postmaster cannot forward anything to its children or release shared memory and semaphores. Backends can be left running, and the next start then fails with `pre-existing shared memory block ... is still in use` until those orphans are killed. Immediate mode stops the children first, then exits.
  • Why can a fast shutdown still take minutes?
    It ends with a shutdown checkpoint that writes every dirty buffer at full speed, and it does not fully stop until walsenders have sent outstanding WAL to connected standbys. A manual `CHECKPOINT` just before the stop and a larger `pg_ctl -t` make the window predictable.

Closing a shop at night. Smart: lock the front door and wait for every customer to leave, even the one lingering over a coffee. Fast: announce closing, void the sales still open at the tills, walk everyone out, then do the end-of-day count. Immediate: everyone out through the fire exit now; the count is rebuilt from the receipt rolls before opening tomorrow.

  • Smart is pg_ctl stop's default, so it waits for clients to leave.
  • Fast shutdown skips the checkpoint, so the next start must replay WAL.
  • Under default settings an immediate shutdown loses acknowledged commits.
  • kill -9 on the postmaster is just a quicker immediate shutdown.
  • Smart shutdown only waits for running queries, not idle sessions.