(KO) PostgreSQL 유틸리티 — 섹션 개요

이 섹션이 다루는 것
계층 구조: 서버 바깥에 위치한 도구들, 그리고 접촉하는 계약별 묶음
읽기 순서
세부 문서 요약
인접 섹션

이 섹션이 다루는 것

이 서브카테고리는 도구 트리다. src/bin/ 아래 독립 실행형 프로그램들, 그리고 클러스터 생성 도구가 의존하는 빌드 타임 코드 생성기(catalog/genbki.pl)와 백엔드 모드(bootstrap/bootstrap.c) 하나씩이 여기에 속한다. 이 문서들이 공유하는 결정적 특성이 있다. 나머지 열두 서브카테고리와 이 섹션을 가르는 기준은 바로 이것이다. 여기에 있는 것은 아무것도 postmaster의 공유 메모리 머신 안에서 실행되지 않는다. 이것들은 모두 별도 실행 파일이다. 이 도구들은 클러스터 바깥에서 작용한다. 실행 중인 서버에 FE/BE 와이어 프로토콜로 말을 걸거나, 정지된 클러스터(또는 스냅샷된 파일)의 온디스크 파일을 직접 읽고 쓰거나, initdb처럼 서버가 존재하기 전에 클러스터를 만드는 방식으로 동작한다.

여기서 다루는 도구를 구체적으로 나열하면 다음과 같다. initdb와 그 뒤에서 동작하는 bootstrap/genbki 카탈로그 코드 생성; pg_dump / pg_restore / pg_dumpall; pg_upgrade; pg_basebackup; pg_combinebackup; pg_rewind; pg_waldump; psql; 그리고 pg_ctl / pg_controldata.

경계의 명확한 표현 — 이 섹션이 소유하지 않는 것:

도구가 호출하는 메커니즘 자체는 다른 서브카테고리에 있다. 도구는 온디스크 또는 온와이어 계약의 클라이언트다. 계약 자체는 다른 곳이 소유한다. pg_waldump는 WAL 레코드를 디코딩하지만, WAL 형식과 리소스 매니저 desc 콜백은 txn-recovery(postgres-wal-records-rmgr.md)가 소유한다. pg_basebackup은 베이스 백업을 스트리밍하지만, 서버 측 BASE_BACKUP 복제 명령, WAL 요약, 백업 매니페스트는 replication-ha가 소유한다. pg_controldata는 pg_control을 출력하지만, ControlFileData 구조체와 그 업데이트 경로는 txn-recovery(postgres-xlog-wal.md)가 소유한다. 규칙은 간단하다. 이 섹션은 실행 파일을 소유하고, 형식과 프로토콜은 그것을 정의하는 서브카테고리에 넘긴다.
카탈로그 내용은 system-catalog에 속한다. genbki.pl은 코드 생성 파이프라인(헤더 + .dat → .bki)으로서 여기서 다루지만, 카탈로그 자체가 무엇인지(pg_class, pg_proc, 그것들을 읽는 relcache)는 system-catalog(postgres-system-catalogs.md)가 소유한다.
src/bin/pg_basebackup/에 함께 있는 복제 전용 프런트엔드 도구들 — pg_receivewal, pg_recvlogical, pg_createsubscriber — 은 유틸리티가 아니라 replication-ha 범위다. 이 섹션이 해당 디렉터리에서 다루는 도구가 하나뿐인데 디렉터리가 더 큰 이유를 설명하기 위해 이름만 언급한다.
contrib/는 전체 트리에서 범위 밖이다. src/bin/에 있지만 플랜의 모듈 카탈로그에 없는 도구들 — pg_amcheck, pgbench, pg_resetwal, pg_checksums, pg_verifybackup 등 — 은 이 섹션의 범위 밖이며 예시로만 이름을 언급할 수 있다.

계층 구조: 서버 바깥에 위치한 도구들, 그리고 접촉하는 계약별 묶음

솔직히 말하면 이것은 계층 스택이 아니다. 클러스터의 세 가지 온디스크/온와이어 계약을 둘러싼 외부 실행 파일들의 테두리가 더 적확한 그림이다. 세 계약이란 카탈로그/.bki 생성 경로, FE/BE 프로토콜, WAL + 데이터 파일 온디스크 형식이다. 각 도구는 자신이 접촉하는 계약에 따라 위치가 정해진다.

flowchart TB
  subgraph BUILD["빌드 타임 (클러스터 없음)"]
    GENBKI["genbki.pl<br/>pg_*.h + pg_*.dat -> postgres.bki<br/>(postgres-initdb-bootstrap-genbki.md)"]
  end

  subgraph GENESIS["클러스터 생성"]
    INITDB["initdb<br/>'postgres --boot'으로 postgres.bki를 재실행,<br/>시스템 뷰 작성, pg_control 기록<br/>(postgres-initdb-bootstrap-genbki.md)"]
  end
  GENBKI -- "postgres.bki" --> INITDB

  subgraph CLUSTER["디스크 위 클러스터 (PGDATA)"]
    direction LR
    CTRL["pg_control"]
    DATA["base/ 데이터 파일"]
    WAL["pg_wal/ + 요약"]
  end
  INITDB -- "생성" --> CLUSTER

  subgraph FEBE["FE/BE 프로토콜 경유 (서버 실행 중)"]
    DUMP["pg_dump / pg_restore / pg_dumpall<br/>스키마+데이터 SQL 또는 아카이브<br/>(postgres-pg-dump-restore.md)"]
    PSQL["psql<br/>대화형 클라이언트 + 메타 명령<br/>(postgres-psql.md)"]
    BASE["pg_basebackup<br/>BASE_BACKUP + WAL 스트림<br/>(postgres-pg-basebackup.md)"]
  end
  DUMP <--> CLUSTER
  PSQL <--> CLUSTER
  BASE <-- "스트리밍" --> CLUSTER

  subgraph OFFLINE["온디스크 파일 직접 접근 (서버 정지 / 스냅샷)"]
    UPGRADE["pg_upgrade<br/>스키마 덤프 + relfilenode 교체<br/>(postgres-pg-upgrade.md)"]
    COMBINE["pg_combinebackup<br/>전체 + 증분 -> 합성 전체<br/>(postgres-pg-basebackup.md 동반 문서)"]
    REWIND["pg_rewind<br/>분기된 데이터 디렉터리 -> 소스 타임라인<br/>(postgres-pg-rewind.md)"]
    WALDUMP["pg_waldump<br/>rmgr desc 콜백으로 WAL 디코딩<br/>(postgres-pg-waldump.md)"]
    CTLDATA["pg_ctl / pg_controldata<br/>postmaster 생명주기 + pg_control 읽기<br/>(postgres-pg-ctl-controldata.md)"]
  end
  UPGRADE --> CLUSTER
  COMBINE --> CLUSTER
  REWIND --> CLUSTER
  WALDUMP --> WAL
  CTLDATA --> CTRL

앞으로 가져가야 할 구조적 사실 두 가지가 있다.

genbki.pl은 빌드 시 한 번만 실행되고, 런타임에는 실행되지 않는다. 이것은 C 프로그램이 아니라 Perl 스크립트다. 카탈로그 헤더 파일과 그것의 .dat 짝에서 postgres.bki(그리고 pg_*_d.h 같은 심볼 헤더들)를 생성한다. initdb는 그 .bki를 부트스트랩 모드(postgres --boot)로 구동된 백엔드에 넘겨 재실행한다. 그 인터프리터가 bootstrap.c다. 빌드 타임 생성기와 백엔드 모드가 한 도구의 이야기로 묶이는 곳은 전체 트리에서 여기뿐이다. 그래서 둘이 하나의 세부 문서로 합쳐진다.
“오프라인” 도구들은 서버가 내려가 있거나(또는 파일이 일관된 스냅샷 상태임을) 전제한다. pg_upgrade, pg_rewind, pg_combinebackup은 PGDATA를 직접 읽거나 재작성한다. 살아 있는 클러스터에 적용하면 데이터가 손상된다. 이 공통 전제가 프로토콜로 서버에 말을 거는 도구들과 이들을 별개의 계열로 구분하는 이유다.

읽기 순서

교차 참조를 먼저 잡는 순서로 읽는다. 클러스터 존재를 전제하는 도구들보다 클러스터 생성 도구를 먼저 읽고, 그 다음에 내보내기/마이그레이션 쌍을, 마지막으로 물리 도구들을 읽는다.

postgres-initdb-bootstrap-genbki.md — 여기서 시작한다. 클러스터가 어디서 오는지, 카탈로그가 어떻게 디스크에 올라가는지를 설명한다. 다른 모든 도구가 이것을 전제하기 때문이다. .bki가 무엇을 채우는지를 함께 잡으려면 postgres-system-catalogs.md와 병행해 읽는다.
postgres-psql.md — 다른 모든 도구의 효과를 관찰할 때 쓰는 클라이언트다. 가볍고, FE/BE 프로토콜을 프런트엔드 쪽에서 이해하는 데 좋은 출발점이다.
postgres-pg-dump-restore.md — 논리 내보내기 모델(아카이브 형식, 의존성 순서 복원). pg_upgrade를 읽기 전에 먼저 읽어야 한다. pg_upgrade가 이 위에서 만들어지기 때문이다.
postgres-pg-upgrade.md — 스키마 전용 덤프와 relfilenode 물리 교체를 합성한다. dump/restore와 스토리지 레이아웃을 모두 익힌 뒤에야 의미가 들어온다.
postgres-pg-basebackup.md (pg_combinebackup 동반 문서 포함) — 물리 백업 경로. 서버 측 BASE_BACKUP 명령과 증분 백업 WAL 요약은 replication-ha를 교차 참조한다.
postgres-pg-rewind.md — 분기된 데이터 디렉터리를 소스 타임라인에 재동기화한다. 베이스 백업과 txn-recovery의 타임라인 개념을 먼저 읽은 뒤에 읽는다.
postgres-pg-waldump.md — WAL 검사. postgres-wal-records-rmgr.md를 먼저 읽어서 재사용하는 rmgr desc 콜백이 낯설지 않은 상태에서 읽는다.
postgres-pg-ctl-controldata.md — postmaster 생명주기 래퍼와 pg_control 리더. pg_control이 다른 모든 도구가 결국 신뢰하는 파일이므로 마무리로 읽기에 적합하다.

세부 문서 요약

아래는 선행 참조다. 모듈 문서가 아직 존재하지 않을 수 있다. 각 행은 범위에 대한 예측적 한 줄 서술이다.

모듈 문서	다룰 내용
`postgres-initdb-bootstrap-genbki.md`	클러스터 생성 파이프라인: `genbki.pl`이 빌드 타임에 `pg_.h` + `pg_.dat` 카탈로그 소스를 `postgres.bki`로 변환하는 방법, `initdb`가 부트스트랩 모드(`bootstrap.c`)의 독립 백엔드로 해당 스크립트를 재실행해 `template1`을 채우고, 시스템 뷰 SQL을 실행하고, `pg_control`에 기록하는 방법.
`postgres-pg-dump-restore.md`	논리 내보내기/복원 모델: `pg_dump`가 FE/BE 프로토콜로 카탈로그를 걸어서 TOC 기반 아카이브로 만드는 방법, `pg_dump_sort`가 의존성 순서로 객체를 정렬하는 방법, `pg_backup_archiver` 엔진이 plain/custom/directory/tar 형식을 내보내는 방법, `pg_restore`(병렬 복원 포함)가 재실행하는 방법, 그리고 전역 객체를 위한 `pg_dumpall`.
`postgres-pg-upgrade.md`	메이저 버전 인플레이스 업그레이드: 구 클러스터에서 스키마만 덤프하고, 새 클러스터를 `initdb`로 만들고, 데이터를 다시 로드하는 대신 relfilenode 파일을 이동하는 방법. 파일 교체를 안전하게 만드는 일관성 검사(`check.c`), relfilenumber 매핑, 데이터베이스별 병렬 오케스트레이션.
`postgres-pg-basebackup.md`	물리 베이스 백업 클라이언트: `BASE_BACKUP` 복제 명령 발행 방법, 데이터 디렉터리와 동시 WAL 스트리밍(`walmethods`/`receivelog` 경로), 압축 적용, 백업 매니페스트 작성 방법. 전체 백업과 증분 백업을 합성 전체로 합치는 `pg_combinebackup` 동반 내용 포함.
`postgres-pg-rewind.md`	분기된 데이터 디렉터리를 소스 타임라인에 재동기화: 마지막 공통 체크포인트부터 WAL을 재실행해 파일 맵을 만드는 방법(`parsexlog.c`, `filemap.c`), 새 베이스 백업 대신 로컬 또는 libpq 소스에서 변경된 블록만 복사하는 방법.
`postgres-pg-waldump.md`	WAL 디코더: `pg_waldump`가 프런트엔드 `XLogReader`로 원시 WAL 세그먼트를 읽고, 백엔드가 사용하는 것과 동일한 rmgr별 `desc` 콜백을 연결해(`rmgrdesc.c`) 각 레코드를 사람이 읽을 수 있게 렌더링하는 방법. 필터링, 통계, follow 모드 포함.
`postgres-psql.md`	대화형 터미널 클라이언트: 읽기/평가 루프(`mainloop.c`), 역슬래시 메타 명령 디스패치, 변수와 `\set` 처리, `\d` 뒤에서 동작하는 `describe.c` 카탈로그 인트로스펙션 쿼리, 쿼리 버퍼링, `COPY`/페이저 통합 — 모두 libpq 위 프런트엔드로서.
`postgres-pg-ctl-controldata.md`	클러스터 생명주기와 컨트롤 파일 검사: `pg_ctl`이 postmaster를 생성/시그널링하고 준비 상태를 폴링해 시작/정지/리로드/프로모트하는 방법, `pg_controldata`가 `xlog.c`에서 백엔드가 기록하는 것과 같은 컨트롤 파일 레이아웃을 사용해 `ControlFileData` 구조체(상태, 체크포인트 LSN, 타임라인, 설정)를 읽고 출력하는 방법.

인접 섹션

txn-recovery (postgres-overview-txn-recovery.md) — 가장 가까운 이웃. pg_waldump가 재사용하는 WAL 레코드 형식과 rmgr desc 콜백, pg_controldata가 출력하고 pg_rewind가 읽는 ControlFileData/pg_control 계약, pg_rewind와 베이스 백업 뒤에 있는 타임라인·체크포인트 개념을 txn-recovery가 소유한다. 유틸리티는 txn-recovery가 디스크에 정의하는 모든 것의 외부 독자다.
replication-ha (postgres-overview-replication-ha.md) — 서버 측 BASE_BACKUP 명령, WAL 요약, 백업 매니페스트, 그리고 pg_basebackup / pg_combinebackup이 클라이언트로서 쓰는 증분 백업 기계를 소유한다. src/bin/pg_basebackup/ 디렉터리를 공유하지만 이 섹션에 속하지 않는 복제 전용 프런트엔드 도구들(pg_receivewal, pg_recvlogical, pg_createsubscriber)도 replication-ha가 소유한다.
system-catalog (postgres-overview-system-catalog.md) — genbki.pl이 채우고 pg_dump와 psql의 \d가 인트로스펙트하는 카탈로그 테이블을 소유한다. genesis 문서가 .bki를 생성하고, system-catalog가 .bki가 의미하는 것을 소유한다.
client-protocol (postgres-overview-client-protocol.md) — psql, pg_dump, pg_basebackup이 프런트엔드로서 사용하는 FE/BE 와이어 프로토콜과 인증을 소유한다. 유틸리티는 프로토콜 클라이언트이고, client-protocol이 프로토콜 자체를 소유한다.
server-architecture (postgres-overview-server-architecture.md) — pg_ctl이 시작하고 정지하는 postmaster, 그리고 initdb가 구동하는 부트스트랩 모드 백엔드를 소유한다. 유틸리티는 server-architecture가 정의하는 생명주기를 감싸는 도구다.