pg_ctl

PostgreSQL server instance를 초기화, 시작, 중지, 재시작, 상태 확인할 때 쓰는 control utility다.

• pg_ctl은 주로 initdb, postgres, PGDATA 기반 서버 lifecycle 제어에 사용한다.
• 서비스 관리자가 없는 개발/테스트 환경에서는 직접 쓰기 편하지만, systemd 같은 service manager가 있는 운영 환경에서는 service unit과 혼용하지 않는 편이 안전하다.
• 중지 시 기본 모드는 fast이며, immediate는 crash recovery를 유발할 수 있으므로 긴급 상황이 아니면 피한다.

pg_ctl initdb -D /var/lib/postgresql/17/main
pg_ctl start -D "$PGDATA" -l /var/log/postgresql/server.log
pg_ctl stop -D "$PGDATA" -m fast
pg_ctl restart -D "$PGDATA" -m fast
pg_ctl reload -D "$PGDATA"
pg_ctl status -D "$PGDATA"
pg_ctl promote -D "$PGDATA"
pg_ctl kill TERM 12345

• pg_ctl initdb [-D DATADIR] [-s] [-o OPTIONS]
• pg_ctl start [-D DATADIR] [-l FILE] [-W] [-t SECS] [-s] [-o OPTIONS] [-p PATH] [-c]
• pg_ctl stop [-D DATADIR] [-m MODE] [-W] [-t SECS] [-s]
• pg_ctl restart [-D DATADIR] [-m MODE] [-W] [-t SECS] [-s] [-o OPTIONS] [-c]
• pg_ctl reload [-D DATADIR] [-s]
• pg_ctl status [-D DATADIR]
• pg_ctl promote [-D DATADIR] [-W] [-t SECS] [-s]
• pg_ctl kill SIGNALNAME PID

• -D, –pgdata data directory 지정. 생략하면 PGDATA 환경 변수를 사용한다.
• -l, –log 서버 로그를 파일에 append한다.
• -o, –options postgres 또는 initdb에 추가 옵션을 전달한다.
• -m, –mode 종료 모드 선택. smart, fast, immediate 중 하나를 쓴다.
• -w, –wait 작업 완료까지 기다린다. 현재 help 기준 기본 동작이다.
• -W, –no-wait 대기하지 않고 즉시 반환한다.
• -t, –timeout -w 대기 시 timeout 초 지정
• -s, –silent informational message를 줄이고 오류만 출력
• -c, –core-files postgres가 core file을 만들 수 있게 허용
• -p postgres 실행 파일 path 지정. 보통 직접 지정할 일은 드물다.

# 새 데이터 디렉터리 초기화
pg_ctl initdb -D /srv/postgres/17/main
 
# 로그 파일을 남기며 서버 시작
pg_ctl start -D /srv/postgres/17/main -l /srv/postgres/17/main/server.log
 
# 포트와 listen_addresses를 임시 오버라이드해서 시작
pg_ctl start -D "$PGDATA" -o "-p 55432 -c listen_addresses=127.0.0.1"
 
# 설정 파일 변경 후 재기동 없이 다시 읽기
pg_ctl reload -D "$PGDATA"
 
# 정상 종료 대기
pg_ctl stop -D "$PGDATA" -m smart
 
# 일반적인 빠른 종료
pg_ctl stop -D "$PGDATA" -m fast
 
# standby를 primary로 승격
pg_ctl promote -D "$PGDATA" -W

• no database directory specified가 나오면 -D를 주거나 PGDATA가 올바른지 확인한다.
• another server might be running 또는 postmaster.pid 관련 오류가 나오면 중복 기동 여부와 stale PID file 상황을 먼저 점검한다.
• pg_ctl start 후 바로 종료되면 -l 로그 파일 또는 data directory 아래 로그를 확인한다. 실제 실패 원인은 보통 postgres가 기록한다.
• 운영 환경에서 systemd service가 관리하는 cluster를 pg_ctl로 직접 중지/시작하면 상태 인식이 꼬일 수 있다. service manager 기준 명령과 혼용하지 않는다.
• immediate 종료 뒤에는 다음 기동 시 recovery가 발생할 수 있다. 장애 격리 목적이 아니면 fast 또는 smart를 우선 사용한다.

• 이 페이지의 도움말은 현재 로컬 환경의 pg_ctl (PostgreSQL) 10.23 출력 기준이다.
• PostgreSQL major version과 배포판 packaging에 따라 기본 data directory 경로, service unit 이름, wrapper command가 달라질 수 있다.
• Debian/Ubuntu 계열은 pg_ctlcluster 같은 배포판 wrapper를 함께 제공하는 경우가 있다. 그런 환경에서는 배포판 표준 운영 방식과 충돌하지 않게 선택한다.

pg_ctl --help

pg_ctl is a utility to initialize, start, stop, or control a PostgreSQL server.
 
Usage:
  pg_ctl init[db] [-D DATADIR] [-s] [-o OPTIONS]
  pg_ctl start    [-D DATADIR] [-l FILENAME] [-W] [-t SECS] [-s]
                  [-o OPTIONS] [-p PATH] [-c]
  pg_ctl stop     [-D DATADIR] [-m SHUTDOWN-MODE] [-W] [-t SECS] [-s]
  pg_ctl restart  [-D DATADIR] [-m SHUTDOWN-MODE] [-W] [-t SECS] [-s]
                  [-o OPTIONS] [-c]
  pg_ctl reload   [-D DATADIR] [-s]
  pg_ctl status   [-D DATADIR]
  pg_ctl promote  [-D DATADIR] [-W] [-t SECS] [-s]
  pg_ctl kill     SIGNALNAME PID
 
Common options:
  -D, --pgdata=DATADIR   location of the database storage area
  -s, --silent           only print errors, no informational messages
  -t, --timeout=SECS     seconds to wait when using -w option
  -V, --version          output version information, then exit
  -w, --wait             wait until operation completes (default)
  -W, --no-wait          do not wait until operation completes
  -?, --help             show this help, then exit
If the -D option is omitted, the environment variable PGDATA is used.
 
Options for start or restart:
  -c, --core-files       allow postgres to produce core files
  -l, --log=FILENAME     write (or append) server log to FILENAME
  -o, --options=OPTIONS  command line options to pass to postgres
                         (PostgreSQL server executable) or initdb
  -p PATH-TO-POSTGRES    normally not necessary
 
Options for stop or restart:
  -m, --mode=MODE        MODE can be "smart", "fast", or "immediate"
 
Shutdown modes are:
  smart       quit after all clients have disconnected
  fast        quit directly, with proper shutdown (default)
  immediate   quit without complete shutdown; will lead to recovery on restart
 
Allowed signal names for kill:
  ABRT HUP INT QUIT TERM USR1 USR2
 
Report bugs to <[email protected]>.

• postgresql
• psql
• pg_restore
• pg_hba.conf

• codex:: 2026-06-28 Created pg_ctl reference page with lifecycle commands, shutdown modes, and operational cautions.