PostgreSQL server instance를 초기화, 시작, 중지, 재시작, 상태 확인할 때 쓰는 control utility다.
pg_ctl은 주로 initdb, postgres, PGDATA 기반 서버 lifecycle 제어에 사용한다.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가 기록한다.pg_ctl로 직접 중지/시작하면 상태 인식이 꼬일 수 있다. service manager 기준 명령과 혼용하지 않는다.immediate 종료 뒤에는 다음 기동 시 recovery가 발생할 수 있다. 장애 격리 목적이 아니면 fast 또는 smart를 우선 사용한다.pg_ctl (PostgreSQL) 10.23 출력 기준이다.pg_ctlcluster 같은 배포판 wrapper를 함께 제공하는 경우가 있다. 그런 환경에서는 배포판 표준 운영 방식과 충돌하지 않게 선택한다.pg_ctl을 직접 실행하기보다 그 관리 계층의 start/stop/restart 절차를 따르는 편이 안전하다.