In PostgreSQL, what do initdb, pg_ctl and the postgres server program each do across a cluster's life, from creation to shutdown?
answer
- one directory, one server
- created once, never per database
- the binary versus its wrapper
- the PID file tells readiness
basics
~20 sinitdb creates a cluster's data directory once; postgres is the server itself, whose first process is the postmaster; pg_ctl is a wrapper that starts, stops, restarts, reloads and reports on that server, tracking it through postmaster.pid.
solid answer
~40 sA PostgreSQL *cluster* is one data directory served by one running server on one port. `initdb -D <dir>` creates it once: the directory tree, the shared catalogs, the `postgres`, `template1` and `template0` databases, and default `postgresql.conf` and `pg_hba.conf`. New databases later come from `CREATE DATABASE`, not from `initdb`. The server program is `postgres`; its first process, the postmaster, locks the directory and forks everything else. You could run `postgres -D <dir>` in the foreground, but `pg_ctl` wraps it: `pg_ctl start -l logfile` detaches it and waits until `postmaster.pid` reports it ready, `pg_ctl stop` signals a shutdown (fast mode by default) and waits for that file to disappear, and `restart`, `reload` and `status` cover the rest.
code
bash · 11 lines# once: create the cluster (as the OS user that will own it)
initdb -D /srv/pg/inventory
# start in the background, log to a file, wait until ready
pg_ctl start -D /srv/pg/inventory -l /var/log/pg/inventory.log
# is it up? exit status 3 means no server is running
pg_ctl status -D /srv/pg/inventory
# stop (fast mode by default) and wait for postmaster.pid to vanish
pg_ctl stop -D /srv/pg/inventorygo deeper
Name the three programs by role: initdb creates the cluster once, postgres is the server, pg_ctl starts and stops it. Say that one server serves every database in the cluster.
Explain how pg_ctl waits on postmaster.pid, why initdb refuses root and non-empty directories, and that pg_ctl stop uses fast mode unless told otherwise.
Show that pg_ctl timing out does not cancel a start or stop, that packaged installs wrap these tools, and when a restart rather than a reload is required.
Treat these tools as part of an operational standard: which initdb choices are expensive to change later, and how start and stop are automated the same way on every host.
## What a PostgreSQL cluster is In PostgreSQL a **database cluster** is not a group of machines. It is one **data directory** (often referred to by the environment variable `PGDATA`) together with the single running server that manages it. Every database inside that directory, including the default `postgres` database, the templates `template1` and `template0`, and every database created later, is served by the same server on the same port. Two clusters on one host need two data directories, two ports and two servers. Three programs cover the cluster's life: | Program | Role | When you run it | |---|---|---| | `initdb` | Creates the data directory and its initial contents | Once per cluster | | `postgres` | The database server itself; its first process is the **postmaster** | Whenever the cluster should be up | | `pg_ctl` | A wrapper that starts, stops, restarts, reloads and inspects the server | Day-to-day operations | ## initdb: run once per cluster `initdb -D /srv/pg/inventory` builds the directory tree, generates the **shared catalogs** that belong to the whole cluster rather than to one database, creates the three initial databases and writes default `postgresql.conf`, `pg_hba.conf` and `pg_ident.conf` files. Rules worth knowing: - It **refuses to run as root**, because the server must not run as root and must own every file `initdb` creates. - It **refuses a directory that already contains files**, so it cannot overwrite an existing installation. - It restricts the directory to the owner (mode `0700`), or allows group read (`0750`) with `--allow-group-access`. - Choices that are awkward to change later are made here: the bootstrap superuser's name (`-U`), the default authentication written into `pg_hba.conf` (`-A`), the WAL segment size and whether data checksums are on. You never rerun `initdb` to add a database. Inside a running cluster that is `CREATE DATABASE`, or the `createdb` client program that issues it. ## postgres: the server program The server binary is `postgres`. Started as `postgres -D /srv/pg/inventory`, it runs in the foreground and writes its log to standard error. Its first process, traditionally called the **postmaster**, takes the data-directory lock file `postmaster.pid`, allocates shared memory, runs any recovery that is needed, opens the listening sockets, and then forks one backend process per client connection plus a set of auxiliary processes. How those processes split the work is its own topic. The same binary can also run as a **single-user** standalone backend for repair work, which is rarely needed. ## pg_ctl: the control wrapper Starting `postgres` by hand means handling backgrounding, log redirection and detaching from the terminal yourself. `pg_ctl` does that and adds **waiting**: 1. `pg_ctl start -D … -l logfile` launches `postgres` in the background, appends its output to the log file and, by default, waits until the server is ready. 2. `pg_ctl stop -D …` sends a shutdown signal, **fast** mode unless `-m` says otherwise, which rolls back open transactions and disconnects sessions, then waits for the server to exit. 3. `pg_ctl restart` is a stop followed by a start that reuses the command-line options recorded in `postmaster.opts`; it is how settings that need a restart take effect. 4. `pg_ctl reload` sends `SIGHUP`, so the server rereads its configuration files and keeps running. 5. `pg_ctl status` prints the server's PID and command line, or exits with status 3 when no server is running (4 when the data directory is not accessible). 6. `pg_ctl init` simply runs `initdb`; `pg_ctl promote` ends standby mode on a replica. ## How pg_ctl knows what the server is doing `pg_ctl` does not connect over the network to find out. It reads **`postmaster.pid`** in the data directory: the first line is the postmaster's PID, and a later line carries a status word (`starting`, `ready`, `standby` or `stopping`). Startup counts as complete when that file reports the server ready; shutdown counts as complete when the server removes the file. If neither happens within the timeout (`-t`, default 60 seconds, or the `PGCTLTIMEOUT` environment variable), `pg_ctl` exits with a non-zero status, but the start or stop may still finish in the background. ## Packaged installations Distribution packages and container images usually create the cluster with their own wrapper script and run the server under the operating system's service manager. The programs underneath are still `initdb` and `postgres`. The manual's advice holds: if you started the server through the package's provisions, stop it through them too, so the service manager's view of the server stays consistent with reality.
- Why does initdb refuse to run as root, and what does the server check about the data directory at start?The server must not run as root, and it must own the files `initdb` creates, so `initdb` refuses root outright. At start the server checks that the data directory is owned by the user running it ("has wrong ownership" otherwise) and that its permissions are `0700` or `0750`; anything looser fails with "has invalid permissions".
- Can two PostgreSQL servers run on the same data directory?No. The postmaster creates `postmaster.pid` as a lock file; a second server finding a live PID there stops with `FATAL: lock file "postmaster.pid" already exists` and a hint naming the other postmaster's PID. Running two servers on one directory would corrupt it, which is exactly what the lock prevents.
- What is the difference between pg_ctl restart and pg_ctl reload?`reload` only sends `SIGHUP`: the server rereads `postgresql.conf` and `pg_hba.conf` and keeps every session. `restart` stops the server (fast by default) and starts it again with the options saved in `postmaster.opts`, so sessions are dropped; it is needed for settings that only take effect at server start.
- You run initdb again each time you need a new database.
- Each database in the cluster has its own postmaster and port.
- pg_ctl is the server, so killing pg_ctl stops the database.
- pg_ctl stop waits for clients to disconnect unless told otherwise.
- Run initdb and the server as root to avoid permission errors.