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

스트리밍 복제는 PostgreSQL 환경에서 고가용성(HA) 및 읽기 확장성을 달성하기 위한 기본 메커니즘입니다. 기본(마스터) 서버가 하나 이상의 대기(복제본) 서버에 WAL(Write-Ahead Log) 레코드를 지속적으로 스트리밍하도록 구성하면 최소한의 지연으로 데이터 동기화를 보장할 수 있습니다.

이 가이드에서는 pg_basebackup, pg_hba.conf 및 대기 신호 파일을 사용한 비동기 스트리밍 복제를 설명합니다. 작업을 마치면 작동하는 기본-대기 쌍과 실제로 스트리밍 중임을 증명하는 데 필요한 확인 방법을 알게 됩니다.

사전 요구 사항 및 환경 설정

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

서버	역할	IP 주소(예시)
기본	데이터 원본	192.168.1.10
대기	복제본	192.168.1.11

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

1단계: 기본 서버 구성

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

1.1 `postgresql.conf` 수정

기본 구성 파일을 편집합니다. Debian 및 Ubuntu 패키지에서는 일반적으로 /etc/postgresql/<version>/main/postgresql.conf에 있으며, 많은 소스 또는 컨테이너 설치에서는 데이터 디렉터리에 있습니다. 다음 매개변수를 설정합니다.

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

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

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

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

# 대기에서 읽기 전용 쿼리 허용
hot_standby = on

1.2 전용 복제 사용자 생성

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

# PostgreSQL에 연결
sudo -u postgres psql -c "CREATE ROLE replica_user WITH REPLICATION LOGIN PASSWORD '실제-비밀번호-사용';"

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

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

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

1.4 기본 서버 다시 시작

구성 변경 사항을 적용합니다. listen_addresses를 변경한 후에는 다시 시작하는 것이 간단한 옵션입니다. pg_hba.conf만 변경한 경우 다시 로드하는 것으로 충분합니다.

sudo systemctl restart postgresql

2단계: 대기 서버 준비

데이터를 복제하기 전에 대기의 PostgreSQL 서비스가 중지되고 기존 데이터 디렉터리가 비어 있는지 확인하십시오.

2.1 대기 PostgreSQL 서비스 중지

sudo systemctl stop postgresql

2.2 데이터 디렉터리 비우기

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

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

sudo rm -rf $PG_DATA/*

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

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

대기 서버에서 이 명령을 실행합니다.

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`	기본 서버 호스트 이름/IP 주소.
`-D`	로컬 데이터 디렉터리 경로.
`-U`	복제 사용자 이름(`replica_user`).
`-P`	진행률 표시.
`-v`	자세한 출력.
`-R`	복제 구성 파일을 자동으로 생성합니다.

3단계: 대기 구성 및 시작

3.1 대기 구성 확인

2.3단계에서 -R 플래그를 사용한 경우 pg_basebackup이 standby.signal 파일을 생성하고 primary_conninfo 설정을 채웠습니다. 일반적으로 데이터 디렉터리 내에 생성된 postgresql.auto.conf라는 구성 파일에 있습니다.

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에 비밀번호가 포함되어 있는지 또는 인증서 기반 인증을 사용하고 있는지 확인하십시오. pg_hba.conf에서 trust 또는 cert를 사용하는 경우 비밀번호를 생략할 수 있습니다.

3.2 대기 서비스 시작

필요한 신호 파일(standby.signal)이 데이터 디렉터리에 있으므로 서비스는 읽기 전용 대기 모드로 시작되고 즉시 기본 서버에 연결을 시도합니다.

sudo systemctl start postgresql

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

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

4.1 기본 서버에서 확인

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

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

예상 출력 (주요 필드):

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

4.2 데이터 동기화 테스트

데이터 흐름을 확인하려면 기본 서버에서 변경을 실행하고 즉시 대기 서버에서 해당 변경 사항이 있는지 확인합니다.

기본 서버에서:

CREATE TABLE replication_test (id serial primary key, message text);
INSERT INTO replication_test (message) VALUES ('데이터가 성공적으로 동기화되었습니다');

대기 서버에서 (읽기 전용):

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

데이터가 대기 서버에 표시되면 스트리밍 복제가 성공적으로 구성되어 활성화된 것입니다.

모범 사례 및 문제 해결

지속적 연결: 복제 슬롯

선택 사항이지만 복제 슬롯을 적극 권장합니다. 복제 슬롯은 대기 서버가 일시적으로 연결이 끊어지더라도 기본 서버가 대기 서버에 필요한 WAL 세그먼트를 조기에 폐기하지 않도록 보장합니다.