[MacOS] PostgreSQL 레플리카 구조 설정 방법

ShinMinChul·2025년 3월 19일

DATEBASE PostgreSQL

DB Technique

목록 보기

1/2

레플리카 구조를 설정하기 이전에, 이미 PostgreSQL 이 설치되었다고 가정하겠다.

해당 글을 작성하기 위해 사용된 기술 스펙은 이러하다.

PostgreSQL 14
Homebrew
MacOS - M1

자 그럼 여정을 떠나보자.

1. 메인 DB 서버 초기화 및 구동

1-1. 메인 DB 데이터 디렉터리 초기화

일반적으로 Homebrew 설치 시 기본 데이터 디렉터리는 아래 경로로 잡히지만, 여기서는 명시적으로 초기화 과정을 보여주기 위해 main_db라는 디렉터리를 새로 지정해보겠습니다.

# 예시: Homebrew PostgreSQL 설치 경로 확인
#  /usr/local/opt/postgresql@14/bin/initdb 형태일 수 있음
initdb -D /usr/local/var/postgresql@14/main_db

1-2 설정 파일 수정 (wal_level, max_wal_senders 등)

레플리카 DB를 만들기 위해서는 메인 DB의 postgresql.conf에 아래와 같은 파라미터를 적절히 설정해 주어야 합니다.

wal_level: replica 이상(보통 replica나 logical), 여기서는 replica로 설정
max_wal_senders: 동시에 허용할 WAL sender 프로세스 개수 (레플리카 개수보다 넉넉하게)
listen_addresses: 접속을 허용할 IP(로컬 호스트만 사용한다면 'localhost')

/usr/local/var/postgresql@14/main_db/postgresql.conf 파일에서 다음 부분을 수정(또는 추가)합니다:

wal_level = replica
max_wal_senders = 5
listen_addresses = 'localhost'
port = 5432

1-3 pg_hba.conf 수정 (레플리카 접속 허용)

레플리카가 메인 DB에 접속해 WAL을 받아올 수 있어야 합니다. /usr/local/var/postgresql@14/main_db/pg_hba.conf 를 열어서 replication connection을 허용하도록 설정을 추가합니다. 예를 들어 모든 로컬에서의 replication을 허용하려면:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    replication     all             127.0.0.1/32            trust
# IPv6의 경우
host    replication     all             ::1/128                 trust

(실제 운영 환경에서는 trust 보다는 md5나 SCRAM 등 보안 방식을 사용하고, 레플리카용 유저도 별도 생성해서 사용하는 것이 좋습니다.)

1-4. 메인 서버 구동

postgres -D /usr/local/var/postgresql@14/main_db

혹은 백그라운드 서비스를 사용하려면 pg_ctl 명령어 사용:

pg_ctl -D /usr/local/var/postgresql@14/main_db -l logfile start

-l logfile 옵션은 로그 파일을 지정하는 것입니다. 예: /usr/local/var/postgresql@14/main_db/server.log
정상적으로 구동되었는지 ps aux | grep postgres 혹은 로그 파일로 확인합니다.

2. 레플리카 DB(Port : 5433) 서버 초기화 및 구동

2-1 레플리카용 데이터 디렉터리 생성 (pg_basebackup 사용)

PostgreSQL에서 레플리카(Standby) 를 만들기 위해서는 메인 DB의 데이터 파일들을 base backup(기본 백업) 받아서 그대로 복사해온 뒤, standby 환경 설정을 해주어야 합니다. 이때 가장 간단한 방법이 pg_basebackup 툴을 사용하는 것입니다.

레플리카용 폴더 만들기

mkdir -p /usr/local/var/postgresql@14/replica_db

레플리카 DB 데이터를 보관할 디렉터리를 미리 만들어 둡니다.

실제로 pg_basebackup 명령을 실행할 때 -D 옵션을 줘서 자동으로 만들 수도 있지만, 명시적으로 만들어두면 구조 파악이 더 편리합니다.

pg_basebackup 명령어로 메인 DB를 백업

메인 DB(포트 5432)가 정상 구동 중이어야 합니다. 그리고 메인 DB에 접속할 수 있는 유저(보통 postgres 또는 replication 권한 가진 유저)를 이용해 아래 명령을 실행합니다.

pg_basebackup \
  -D /usr/local/var/postgresql@14/replica_db \
  -U postgres \
  -h localhost \
  -p 5432 \
  -P \
  -R \
  -X stream

아래는 각 옵션의 의미입니다:

-D /usr/local/var/postgresql@14/replica_db
백업(복제본) 데이터를 저장할 디렉터리 경로입니다. 여기에서 레플리카 DB가 돌게 됩니다.
-U postgres
메인 DB에 접속하여 백업을 받을 때 사용할 유저 이름입니다. (보통 슈퍼유저 postgres 사용)
-h localhost
메인 DB의 호스트 주소. 로컬에서 동작 중이므로 localhost 사용.
-p 5432
메인 DB가 사용하는 포트. 우리가 “메인 DB = 5432”로 설정했으므로 5432.
-P
백업 진행 상황(Progress)을 터미널에 표시하라는 의미입니다. 복제 진행도를 시각적으로 확인할 수 있습니다.
-R
이 옵션을 주면 standby.signal 파일을 자동으로 만들어주고, postgresql.auto.conf에 레플리카(standby) 관련 설정(primary_conninfo)을 자동으로 써줍니다. 이로써 별도 설정 파일을 건드리지 않고도 standby로 동작하게 됩니다.
-X stream
WAL(Write-Ahead Log) 파일을 스트리밍 방식으로 동시에 받아옵니다. 이를 통해 백업이 끝날 시점의 데이터까지 동기화되도록 만들어 줍니다.

정상적으로 동작하면 디렉터리 /usr/local/var/postgresql@14/replica_db 아래에 메인 DB의 데이터 파일들이 복제되어 생성되고, 내부에 standby.signal 파일 등도 함께 생깁니다

2-2 postgresql.conf에서 포트, listen_addresses 수정

백업 완료 후 /usr/local/var/postgresql@14/replica_db/postgresql.conf 파일을 열어, 레플리카 전용 포트(5433)와 접속 허용 주소 등을 지정합니다.

/usr/local/var/postgresql@14/replica_db/postgresql.conf

port = 5433
listen_addresses = 'localhost'

port = 5433
레플리카 인스턴스가 5433 포트로 동작하게 하려고 지정합니다.

listen_addresses = 'localhost'
외부 접속 없이 로컬에서만 테스트한다면 'localhost'로 제한하는 것이 안전합니다.

만약 실제로 다른 서버에서 접속해야 한다면 listen_addresses = '*' 로 열고, pg_hba.conf 에서 IP 제한 등을 해주어야 합니다.

2-3 (자동 설정 확인) primary_conninfo, standby.signal 등

-R옵션을 사용했기 때문에, 레플리카 데이터 디렉터리에는 이미 다음과 같은 파일/설정이 자동으로 생겼을 것입니다:

standby.signal: 이 파일이 존재하면 PostgreSQL은 이 디렉터리를 Standby 모드로 인식하여 레플리카로 동작합니다.

postgresql.auto.conf 파일에 아래와 비슷한 설정이 들어갑니다(자동으로 생성됨):

primary_conninfo = 'user=postgres passfile='...snip...' host=localhost port=5432 ...'

여기서 메인 DB(5432)에 접속할 호스트/포트/유저 정보가 포함되어 있으며, 레플리카는 이를 통해 WAL을 받아옵니다.

직접 커스텀이 필요하다면 수동으로 standby.signal 파일을 만들고 postgresql.conf에 primary_conninfo를 써주거나, recovery.conf가 필요했던 예전 버전과 달리 PostgreSQL 12+에서는 이런 작업이 자동/통합되어 있습니다.

2-4 레플리카 DB 구동

이제 레플리카용 데이터 디렉터리 /usr/local/var/postgresql@14/replica_db를 기반으로 PostgreSQL 인스턴스를 기동합니다.

아래 예시는 pg_ctl을 이용한 구동 방법입니다:

pg_ctl -D /usr/local/var/postgresql@14/replica_db \
  -l /usr/local/var/postgresql@14/replica_db/server.log \
  start

-D: 사용할 데이터 디렉터리(지금은 레플리카용)
-l: 로그 파일 경로
start : DB 서버를 시작하라는 명령

정상적으로 구동되면, 이 레플리카 서버는 포트 5433에서 메인(5432)에 연결해 WAL을 받아오는 Standby 모드로 작동합니다.

동작 여부는 ps aux | grep postgres 프로세스 확인, 또는 /usr/local/var/postgresql@14/replica_db/server.log 안의 로그를 보고 점검할 수 있습니다.

postgres: startup process streaming ... 등의 로그가 보이면 정상적으로 메인 DB와 연결되어 스트리밍 중이라는 뜻입니다.

3. 동작 확인 방법

3-1 메인 DB(5432)에 접속

psql -h localhost -p 5432 -U postgres

임의의 테스트 테이블/데이터를 생성해 봅니다:

CREATE TABLE test_table (id SERIAL PRIMARY KEY, msg TEXT);
INSERT INTO test_table (msg) VALUES ('Hello'), ('Replica'), ('Streaming');

3-2 레플리카 DB(5433)에 접속

- psql -h localhost -p 5433 -U postgres

읽기 전용이므로 INSERT/UPDATE는 제한되지만, SELECT는 가능해야 합니다:

SELECT * FROM test_table;

메인 DB에서 넣은 ('Hello'), ('Replica'), ('Streaming') 데이터가 동일하게 보이는지 확인합니다.

3-3 추가 확인

레플리카 DB에서 SELECT pg_is_in_recovery(); 쿼리를 하면 보통 t (true)가 리턴되어, 현재 이 인스턴스가 Standby(복구 모드) 상태임을 알 수 있습니다.
메인 DB에 새 데이터를 INSERT 후, 레플리카 DB에서 SELECT 했을 때 새 데이터가 거의 실시간(또는 약간 지연)으로 확인되면, 스트리밍 복제가 정상 동작하는 것입니다.

이렇게 하면 한 대의 macOS 머신에서 포트 5432(메인)와 포트 5433(레플리카)로 두 개의 PostgreSQL 14 인스턴스를 동시에 구동하는 스트리밍 복제를 손쉽게 테스트할 수 있습니다.

운영 환경에서는 보안(인증 방식, 방화벽, SSH 터널 등), 모니터링, 장애조치(failover) 정책 등을 더욱 철저히 구성해야 합니다. 그러나 기본적인 “로컬 환경에서의 PostgreSQL 복제”는 위 단계를 거치면 충분히 동작을 확인할 수 있습니다.

ShinMinChul

개발은 예술이며, 나는 예술가다.

다음 포스트