postgresql:pg_ctl [Command Line Interface Helper]

이 문서는 읽기 전용입니다. 원본을 볼 수는 있지만 바꿀 수는 없습니다. 문제가 있다고 생각하면 관리자에게 문의하세요.
{{tag>[cli postgres postgresql server daemon cluster]}}

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

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

===== Usage =====
<code bash>
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
</code>

  * ''<color #c3c3c3>**pg_ctl**</color> <color #ff7f27>initdb</color> <color #22b14c>[-D DATADIR] [-s] [-o OPTIONS]</color>''
  * ''<color #c3c3c3>**pg_ctl**</color> <color #ff7f27>start</color> <color #22b14c>[-D DATADIR] [-l FILE] [-W] [-t SECS] [-s] [-o OPTIONS] [-p PATH] [-c]</color>''
  * ''<color #c3c3c3>**pg_ctl**</color> <color #ff7f27>stop</color> <color #22b14c>[-D DATADIR] [-m MODE] [-W] [-t SECS] [-s]</color>''
  * ''<color #c3c3c3>**pg_ctl**</color> <color #ff7f27>restart</color> <color #22b14c>[-D DATADIR] [-m MODE] [-W] [-t SECS] [-s] [-o OPTIONS] [-c]</color>''
  * ''<color #c3c3c3>**pg_ctl**</color> <color #ff7f27>reload</color> <color #22b14c>[-D DATADIR] [-s]</color>''
  * ''<color #c3c3c3>**pg_ctl**</color> <color #ff7f27>status</color> <color #22b14c>[-D DATADIR]</color>''
  * ''<color #c3c3c3>**pg_ctl**</color> <color #ff7f27>promote</color> <color #22b14c>[-D DATADIR] [-W] [-t SECS] [-s]</color>''
  * ''<color #c3c3c3>**pg_ctl**</color> <color #ff7f27>kill</color> <color #7092be>SIGNALNAME PID</color>''

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

===== Examples =====
<code bash>
# 새 데이터 디렉터리 초기화
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
</code>

===== Troubleshooting =====
  * ''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''를 우선 사용한다.

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

<note warning>
systemd, docker entrypoint, Kubernetes operator처럼 상위 orchestrator가 PostgreSQL 프로세스를 관리하는 환경에서는 ''pg_ctl''을 직접 실행하기보다 그 관리 계층의 start/stop/restart 절차를 따르는 편이 안전하다.
</note>

===== Help =====
++++ pg_ctl --help |
<code text>
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 <pgsql-bugs@postgresql.org>.
</code>
++++

===== See Also =====
  * [[postgresql:ko]]
  * [[postgresql:psql]]
  * [[postgresql:pg_restore]]
  * [[postgresql:config:pg_hba.conf]]

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