pg_ctl: Usage, Options & Common CI Errors
pg_ctl initializes, starts, stops, and reloads a PostgreSQL server instance.
pg_ctl is used when CI runs Postgres directly on the runner instead of in a service container. The whole flow hinges on PGDATA pointing at a valid, initialized data directory.
What it does
pg_ctl is a utility for controlling a PostgreSQL server process: initializing a data directory, starting and stopping the server, reloading config, and reporting status. It operates on a data directory given by -D or the PGDATA environment variable.
Common usage
pg_ctl init -D ./pgdata
pg_ctl -D ./pgdata -l logfile -w start # wait until ready
pg_ctl -D ./pgdata status
pg_ctl -D ./pgdata -m fast stop
pg_ctl -D ./pgdata reloadOptions
| Action / flag | What it does |
|---|---|
| init | Initialize a new data directory (initdb) |
| start / stop / restart | Control the server process |
| -D <dir> | Data directory (or set PGDATA) |
| -w / -W | Wait / do not wait for completion |
| -l <file> | Redirect server log to a file |
| -m smart|fast|immediate | Shutdown mode |
Common errors in CI
pg_ctl: directory "./pgdata" is not a database cluster directory - run pg_ctl init (or initdb) first. "another server might be running" / "lock file already exists" means a stale postmaster.pid from a previous job; remove it or use a fresh data dir. Without -w, start returns before the server accepts connections, so a following psql races it - use -w start or poll with pg_isready.