skip to content

When is starting PostgreSQL in single-user mode with postgres --single the right tool, and what does that mode switch off?

level: seniorimportance: nice to knowfreq 14%

answer

  1. no postmaster, no network
  2. user ID 1 with full powers
  3. newline ends the command
  4. catalog indexes you cannot trust

basics

~20 s

Single-user mode runs one standalone backend with no postmaster, no network, no background processes and implicit superuser rights; use it for catalog repair, such as -P with REINDEX SYSTEM, or when no normal superuser login works.

solid answer

~40 s

`postgres --single -D <dir> <dbname>` starts one backend directly on the data directory, with no postmaster, no listening socket and no background processing: no automatic checkpoints, no autovacuum, no replication. The session runs as the user with ID 1, the bootstrap superuser, with superuser powers. `initdb` uses this mode internally; operators use it for repairs that a normal server cannot do, mainly corrupted system catalog indexes (`-P` ignores them while you `REINDEX SYSTEM`) or regaining control when no superuser login path works. Input is primitive: a newline ends a command unless you use `-j`, and EOF (Ctrl-D) exits. It takes the same `postmaster.pid` lock, so the normal server must be down, and `pg_ctl` refuses to stop it. For XID wraparound the manual now says to avoid it and use a normal-mode `VACUUM`.

code

bash · 10 lines
bash
# the regular server must be down: single-user takes the same lock
pg_ctl stop -D /srv/pg/inventory -m fast

# --single first; -P ignores damaged system indexes while reading catalogs
postgres --single -P -D /srv/pg/inventory inventory
# at the backend> prompt, one line is one command:
#   REINDEX SYSTEM inventory
# then Ctrl-D (EOF) to exit cleanly with a shutdown checkpoint

pg_ctl start -D /srv/pg/inventory -l /var/log/pg/inventory.log

go deeper

for a junior

Know that postgres --single exists, runs one backend with no network, and is a repair tool rather than a normal way to run PostgreSQL.

for a middle

Explain what the mode switches off, how input and exit work, and why the regular server must be stopped first.

for a senior

Name real uses, such as -P with REINDEX SYSTEM for damaged catalog indexes, prefer non-downtime alternatives, and know the manual now discourages it for wraparound.

for a principal

Keep single-user procedures in the break-glass runbook with their downtime cost stated, and make sure normal superuser access paths exist so it is rarely needed.

## What single-user mode is The `postgres` binary normally starts as a **postmaster** that listens for connections and forks a backend per client. Started as `postgres --single`, where `--single` must be the first argument, it instead becomes **one standalone backend** that reads commands from standard input and writes results to standard output. There is no postmaster, no TCP or Unix socket, and no other session. The session user is the role with **ID 1**, the bootstrap superuser created by `initdb`, and it has superuser powers. The manual notes that this user does not actually have to exist, which is why the mode can repair some kinds of accidental damage to the system catalogs. `initdb` itself uses this mode to bootstrap a new cluster. For operators it is a rarely needed repair tool. ## What it switches off | Normal server | Single-user mode | |---|---| | Postmaster supervises many backends | One process, no supervision | | Clients connect over sockets | Only the terminal that started it | | Automatic checkpoints | None while it runs | | Autovacuum | None | | Replication to standbys | None | | psql line editing and history | None; a bare input loop with a `backend>` prompt | On startup the standalone backend runs crash recovery itself if the cluster was not shut down cleanly, and on a clean exit it writes a shutdown checkpoint. Because nothing checkpoints in between, a long session followed by a crash means a long recovery. There is also no supervisor: if the standalone backend dies, nothing restarts it, and the next start of either kind begins with crash recovery. Long-running maintenance therefore belongs in a normal server whenever that is possible, with single-user mode kept for the short repair that truly needs it. ## Talking to a single-user backend - By default a **newline ends a command**; to continue a command onto another line, end the line with a backslash. The mode has no psql-style understanding of semicolons. - With `-j`, a semicolon followed by an empty line ends a command instead. - Statements entered together before one terminator run as a **single transaction**. - **EOF** (usually Ctrl-D) exits; if text is pending, the first EOF submits it and a second one exits. The backend writes a **negative PID** into `postmaster.pid`, so `pg_ctl stop` refuses with `cannot stop server; single-user server is running`. You leave by sending EOF, which lets it write its shutdown checkpoint. ## Legitimate uses 1. **Corrupted system catalog indexes.** If a damaged index on a system catalog makes every normal session fail, stop the server and start `postgres --single -P -D <dir> <dbname>`. `-P` makes the backend ignore system indexes when reading catalogs, while still updating them, and `REINDEX SYSTEM` then rebuilds them. A regular session started with `PGOPTIONS=-P` is an alternative when the server still accepts connections; how and when to rebuild indexes is the index-maintenance topic. 2. **No working superuser login.** If no superuser can log in, because of a lost password and no local `peer` route, single-user mode gives a superuser session without authentication. Usually a temporary local `pg_hba.conf` rule and a reload are simpler and need no downtime. Note that the bootstrap superuser cannot have its `SUPERUSER` attribute removed, which closes one classic way of locking yourself out. 3. **Debugging bootstrap problems.** Rare outside PostgreSQL development; the manual warns it is not realistic for debugging, because no real interprocess communication or locking happens. ## When not to use it - **XID wraparound.** Older advice was to stop the server and `VACUUM` in single-user mode. The current manual says to avoid that: it means downtime and it disables the wraparound safeguards. Use a normal-mode `VACUUM` after clearing what holds the horizon back; the only remaining reason for single-user mode there is to `TRUNCATE` or `DROP` tables you do not need. The wraparound procedure belongs to the vacuum topic. - **Anything a normal session can do.** Single-user mode means the whole cluster is down for every application. Prefer a normal superuser session whenever one is possible. - **While the server is running.** It takes the same data-directory lock, so it cannot start alongside a live postmaster, and it must never be forced to.

  • Why does pg_ctl stop refuse to stop a single-user backend, and how do you end it?
    A standalone backend writes the negative of its PID into `postmaster.pid`, and `pg_ctl` reads that as a single-user server and refuses rather than signalling it. You end the session from its own terminal with EOF (Ctrl-D), which lets it write a shutdown checkpoint before exiting.
  • Is single-user mode still the standard fix when the server stops assigning transaction IDs near wraparound?
    No. The current manual says to avoid it: it requires downtime and disables the wraparound safeguards. Resolve old prepared transactions, long transactions and stale replication slots, then run `VACUUM` in normal multi-user mode. Single-user mode remains useful there only to `TRUNCATE` or `DROP` tables you do not need.

  • Single-user mode still runs autovacuum and checkpoints in the background.
  • You can keep the normal server running and open single-user mode beside it.
  • Single-user mode is the standard way to recover from XID wraparound.
  • A semicolon ends each command in single-user mode, just as in psql.
  • pg_ctl stop is the right way to end a single-user session.