PostgreSQL 스트리밍 복제 설정 단계별 가이드

스트리밍 복제는 PostgreSQL 환경에서 고가용성(HA) 및 읽기 확장성(read scalability)을 달성하기 위한 기본적인 메커니즘입니다. 주(master) 서버가 하나 이상의 대기(replica) 서버로 쓰기 선행 로그(WAL) 레코드를 지속적으로 스트리밍하도록 구성함으로써, 최소한의 지연으로 데이터 동기화를 보장합니다.

이 포괄적인 가이드는 강력하고 비동기적인 스트리밍 복제를 구축하는 데 필요한 필수 단계를 안내합니다. 우리는 Primary 및 Standby 서버 모두에 필요한 구성 변경 사항을 다루며, 간소화된 설정을 위해 pg_basebackup 및 시그널 파일과 같은 최신 PostgreSQL 기능을 활용합니다. 이 튜토리얼을 따르면 견고한 PostgreSQL 운영을 위한 신뢰할 수 있는 기반을 갖추게 될 것입니다.

사전 요구 사항 및 환경 설정

시작하기 전에 다음 사전 요구 사항이 충족되었는지 확인하십시오. 이 가이드는 동일한 주 버전의 PostgreSQL(버전 12 이상 권장)을 실행하는 두 개의 서버(Primary 및 Standby)를 가정합니다.

서버	역할	IP 주소 (예시)
Primary	데이터 원본 (Source of truth)	192.168.1.10
Standby	복제본 (Replica)	192.168.1.11

사용자: 두 서버 모두에 관리자 액세스 권한(예: sudo 또는 postgres 시스템 사용자)이 있어야 합니다.
네트워크: Standby 서버는 PostgreSQL 포트(기본값 5432)를 통해 Primary 서버에 연결할 수 있어야 합니다.

1단계: Primary 서버 구성

Primary 서버는 복제를 위해 WAL 파일을 생성하고 제공하도록 구성되어야 합니다.

1.1 `postgresql.conf` 수정

일반적으로 데이터 디렉터리(예: /etc/postgresql/14/main/postgresql.conf)에 있는 기본 구성 파일을 편집하고 다음 매개변수를 설정하십시오:

# 다른 호스트로부터의 연결 허용
listen_addresses = '*'

# WAL 수준을 'replica' 이상으로 설정
wal_level = replica

# 대기 서버로부터의 최대 동시 연결 수
max_wal_senders = 5 

# 동시에 활성화될 수 있는 대기 연결 수를 제어
max_replication_slots = 5

# 대기 서버에서의 읽기 전용 쿼리(Hot Standby)에 필요
hot_standby = on

1.2 전용 복제 사용자 생성

보안을 위해 REPLICATION 속성을 가진 특정 사용자를 생성합니다. 이 사용자는 대기 서버가 WAL 레코드를 가져오는 데만 사용됩니다.

# PostgreSQL에 연결
psql -c "CREATE USER replica_user REPLICATION ENCRYPTED PASSWORD 'SuperSecurePassword123';"

1.3 클라이언트 인증 업데이트 (`pg_hba.conf`)

Standby 서버의 IP 주소에서 복제 사용자가 특수 replication 의사 데이터베이스에 연결할 수 있도록 허용합니다.

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    replication     replica_user    192.168.1.11/32         md5

1.4 Primary 서버 재시작

PostgreSQL 서비스를 재시작하여 변경 사항을 적용합니다:

sudo systemctl restart postgresql

2단계: Standby 서버 준비

데이터를 복제하기 전에 Standby의 PostgreSQL 서비스가 중지되었는지, 기존 데이터 디렉터리가 비워졌는지 확인하십시오.

2.1 Standby PostgreSQL 서비스 중지

sudo systemctl stop postgresql

2.2 데이터 디렉터리 정리

경고: 이 단계는 현재 Standby의 데이터 디렉터리에 있는 모든 데이터를 영구적으로 삭제합니다. 실행하기 전에 경로를 확인하십시오.

# PG 14의 예시 경로
PG_DATA=/var/lib/postgresql/14/main

sudo rm -rf $PG_DATA/*

2.3 `pg_basebackup`을 사용하여 데이터 복제

pg_basebackup을 사용하여 Primary의 데이터 디렉터리 사본을 정확히 생성합니다. -R 플래그는 스트리밍 복제에 필요한 구성 파일(standby.signal 및 primary_conninfo)을 자동으로 생성하므로 매우 중요합니다(PostgreSQL 12+).

이 명령을 Standby 서버에서 실행하십시오:

PG_DATA=/var/lib/postgresql/14/main

sudo -u postgres pg_basebackup -h 192.168.1.10 -D $PG_DATA -U replica_user -P -v -R

옵션	설명
`-h`	Primary 서버 호스트 이름/IP 주소.
`-D`	로컬 데이터 디렉터리 경로.
`-U`	복제 사용자 이름 (`replica_user`).
`-P`	진행률 표시.
`-v`	상세 출력.
`-R`	복제 구성 파일을 자동으로 생성.

3단계: Standby 구성 및 시작

3.1 Standby 구성 확인

2.3단계에서 -R 플래그를 사용했다면, pg_basebackup은 standby.signal 파일을 생성하고, 일반적으로 데이터 디렉터리 내에 생성된 postgresql.auto.conf 파일에 primary_conninfo 설정을 채워 넣습니다.

primary_conninfo 문자열의 내용을 확인하십시오. ( $PG_DATA/postgresql.auto.conf 내부를 확인) 다음과 유사해야 합니다:

primary_conninfo = 'host=192.168.1.10 user=replica_user password=SuperSecurePassword123 application_name=standby_node'

팁: 암호가 primary_conninfo에 포함되어 있는지 또는 인증서 기반 인증을 사용하고 있는지 확인하십시오. trust 또는 cert로 pg_hba.conf를 사용하는 경우 암호는 생략될 수 있습니다.

3.2 Standby 서비스 시작

필수 시그널 파일(standby.signal)이 데이터 디렉터리에 있으므로, 서비스는 읽기 전용 Standby 모드로 시작되며 즉시 Primary에 연결을 시도합니다.

sudo systemctl start postgresql

4단계: 스트리밍 복제 확인

Standby를 시작한 후, 연결이 활성화되어 있고 데이터 동기화가 진행 중인지 확인해야 합니다.

4.1 Primary 서버에서 확인

Primary 서버에 연결하고 pg_stat_replication 뷰를 쿼리합니다. Standby 서버의 연결을 나타내는 행이 표시되어야 합니다.

psql -c "SELECT client_addr, state, sync_state, sent_lsn, write_lsn, flush_lsn FROM pg_stat_replication;"

예상 출력 (핵심 필드):

client_addr: Standby 서버의 IP와 일치해야 합니다(예: 192.168.1.11).
state: streaming이어야 합니다. startup 또는 catching up이 표시되면 잠시 기다리십시오. walsender가 시작 중이면 곧 연결될 것입니다.
sync_state: async여야 합니다(표준 비동기 복제의 경우).

4.2 데이터 동기화 테스트

데이터 흐름을 확인하려면 Primary에서 변경 사항을 실행하고 즉시 Standby에서 그 존재를 확인하십시오.

Primary에서:

CREATE TABLE replication_test (id serial primary key, message text);
INSERT INTO replication_test (message) VALUES ('Data synchronized successfully');

Standby에서 (읽기 전용):

-- 오류 없이 성공해야 합니다
psql -c "SELECT * FROM replication_test;"

Standby에서 데이터가 확인되면 스트리밍 복제가 성공적으로 구성되고 활성화된 것입니다.

모범 사례 및 문제 해결

지속적인 연결: 복제 슬롯

선택 사항이지만, 복제 슬롯(replication slots)은 강력히 권장됩니다. 복제 슬롯은 Standby가 일시적으로 연결을 끊더라도 Primary 서버가 Standby에 필요한 WAL 세그먼트를 시기상조로 폐기하지 않도록 보장합니다.