본문으로 건너뛰기
Docs
Part XI. 백업과 복구
11.3 pg_basebackup

11.3 pg_basebackup

pg_basebackup은 PostgreSQL의 기본 물리 base 백업 도구입니다. 실행 중인 클러스터의 PGDATA를 통째로 복사합니다. PITR 기준점·standby 초기 구축에 표준입니다. pgBackRest·Barman 같은 상용 도구가 내부적으로 이걸 호출합니다.

가장 단순한 사용 

pg_basebackup -h primary.example.com -U repl_user \
              -D /var/lib/pgsql/17/data \
              -X stream -P
옵션의미
-h <host>primary 주소
-U <user>replication 권한 있는 역할
-D <dir>받을 위치 (빈 디렉토리)
-X streamWAL을 별 스레드로 받음 (권장)
-X fetchbase 끝난 뒤 한 번에 받음 (옛 방식)
-P진행률 표시

필요한 권한 

-- replication 역할
CREATE ROLE repl_user WITH REPLICATION LOGIN PASSWORD 'secret';

-- pg_hba.conf에 추가
-- hostssl  replication  repl_user  10.0.0.0/8  scram-sha-256

REPLICATION 속성 또는 pg_read_all_data + 슈퍼유저급. 슈퍼유저는 권장 안 합니다.

출력 형식 

pg_basebackup -D backup_dir/ -F plain                # 기본: 그대로 복사
pg_basebackup -D backup_dir/ -F tar -z                # tar + gzip
pg_basebackup -D backup_dir/ -F tar --compress=lz4   # PG 15+
pg_basebackup -D backup_dir/ -F tar --compress=zstd  # PG 15+
형식메모
plainPGDATA 그대로 복사 — 즉시 시작 가능한 클러스터
tar압축 가능. 외부 저장소에 보내기 편함

-F tar는 tablespace당 1 tar 파일 (base.tar, <oid>.tar).

압축 — server vs client side

PG 15+부터 서버 측 압축 가능합니다.

# 서버 측 (CPU는 primary에서)
pg_basebackup -D out/ -F tar --compress=server-zstd:3

# 클라이언트 측 (CPU는 backup 호스트에서)
pg_basebackup -D out/ -F tar --compress=client-zstd:3

primary CPU 여유 있으면 server 측 압축이 네트워크 절약 — 흔한 선택.

checksum 검증

pg_basebackup --verify-checksums 옵션은 체크섬 활성된 클러스터에서 백업 중 페이지 손상을 검출.

pg_basebackup -D backup/ --verify-checksums

데이터 disk 부패의 조기 알람을 받습니다.

동시 백업 — pg_start_backup/pg_stop_backup 안 씀

PG 15부터 pg_start_backup / pg_stop_backup API가 비공식 사용 금지(non-exclusive mode만 남고, pg_basebackup 또는 새 SQL 함수 pg_backup_start/pg_backup_stop 사용).

운영자가 직접 호출할 일은 거의 없음 — pg_basebackup 또는 pgBackRest가 알아서.

standby 구축

primary가 살아 있는 상태에서 standby 초기 데이터 만들기:

# standby 호스트에서
sudo -u postgres pg_basebackup \
  -h primary.example.com -U repl_user \
  -D /var/lib/pgsql/17/data \
  -X stream -P -R --slot=standby1
옵션의미
-Rstandby.signal + postgresql.auto.conf에 primary_conninfo 자동 추가
--slot=<name>복제 슬롯 사용 (WAL 보장)

기동:

sudo systemctl start postgresql-17

자동으로 standby 모드로 진입 (standby.signal 존재 → recovery 모드).

진행률·진단

PG 13+의 pg_stat_progress_basebackup:

SELECT pid, phase, backup_streamed, backup_total,
       round(100.0 * backup_streamed / nullif(backup_total, 0), 1) AS pct
  FROM pg_stat_progress_basebackup;

대용량 백업의 진행률 실시간 확인합니다.

PITR base 백업

PITR 시나리오의 출발점은 pg_basebackup (또는 pgBackRest의 풀 백업). 이 base에서부터 archive된 WAL을 재생해 원하는 시점으로.

# base 백업
pg_basebackup -D /backup/base_20260523/ -X stream -F tar -z

# 동시에 archive_mode = on, archive_command가 WAL을 외부 저장소로 보내고 있어야

자세한 PITR은 11.4.

한계

한계메모
증분 백업 안 됨 (PG 17까지)base 백업은 항상 전체
외부 저장소 직접 업로드 안 됨tar로 받아 별도 도구로 보내야
보존 정책 자체 관리 안 함운영자가 정리
WAL archive와의 통합 제공 안 함archive_command 따로 설정

이래서 운영 환경에서는 pg_basebackup만 단독으로 쓰지 않고 pgBackRest 또는 Barman으로 감싸는 패턴이 표준입니다.

PG 17의 incremental base backup

PG 17에서 증분 base backup 기능이 들어왔습니다.

# 1. 풀 base 백업
pg_basebackup -D base/ ...

# 2. 일정 시간 후 증분
pg_basebackup -D incr_1/ --incremental=base/backup_manifest

# 복원 시
pg_combinebackup -o full_restored/ base/ incr_1/ incr_2/

증분은 이전 백업 대비 변경된 페이지만 받음 → 백업 크기 ↓, 시간 ↓. pgBackRest는 이전부터 자체 증분 지원 — pg_basebackup도 따라잡은 셈.

운영 시 주의

주의메모
큰 클러스터는 수 시간진행 중 pg_replication_slots의 슬롯 만료 위험
primary I/O 부하--max-rate 옵션으로 throttle 가능 (예: --max-rate=100M)
백업 디렉토리 디스크풀 백업 한 번이 클러스터 크기 + WAL
같은 host에 백업 저장 금지디스크 사고 시 같이 사라짐
운영 자동화는 외부 도구pgBackRest·Barman 권장 (11.5, 11.6)
복제 슬롯 + pg_basebackup: slot으로 백업하면 base 백업 동안 primary의 WAL이 절대 잘리지 않음. 백업이 오래 걸리거나 실패하면 primary pg_wal이 가득 차 클러스터 정지 사고입니다. 항상 모니터링.

정리

  • pg_basebackup = 물리 base 백업의 표준 도구
  • -X stream(WAL 동시 수신) + -R(standby 자동 설정)이 일반적
  • PG 15+ 서버 측 zstd 압축으로 네트워크·디스크 절약
  • PITR base는 pg_basebackup + 외부 archive 결합
  • 증분 백업은 PG 17부터, 그 전엔 pgBackRest 사용
  • 운영 자동화는 pgBackRest/Barman으로 감싸는 게 표준

다음 절(11.4)에서는 그 시점으로 정확히 되돌아가는 — WAL archive와 PITR을 봅니다.

11.2 pg_dump / pg_restore11.4 WAL 아카이브와 PITR