PostgreSQL target_session_attrs 기준 정리

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

PostgreSQL target_session_attrs 기준 정리

target_session_attrs는 libpq가 연결에 성공한 서버가 "내가 원하는 성격의 세션인지"를 한 번 더 검사하는 옵션이다. 2026년 7월 15일 기준 PostgreSQL 18 공식 문서에 따르면 이 값은 여러 호스트를 나열했을 때 첫 번째로 연결 가능한 서버가 아니라, 조건에 맞는 첫 번째 서버를 고르는 데 쓰인다. 장애 조치 구성에서 쓰기 가능한 primary만 붙이고 싶은지, 읽기 전용 standby만 붙이고 싶은지, standby를 우선하되 없으면 아무 서버나 붙어도 되는지 같은 요구를 연결 문자열 단계에서 정리할 수 있다.

핵심은 이 옵션이 로드 밸런서가 아니라 "연결 후 수용 조건"이라는 점이다. libpq는 먼저 접속을 시도한 뒤, 그 세션이 read-write, primary, standby 같은 조건을 만족하는지 확인한다. 조건을 만족하지 않으면 다음 호스트를 계속 시도한다.

target_session_attrs는 정확히 무엇을 검사할까?

공식 문서 기준 이 옵션에는 여섯 가지 모드가 있다. 기본값은 any이며, 나머지는 읽기/쓰기 가능 여부와 hot standby 여부를 기준으로 세션을 걸러낸다.

값	의미	무난한 사용 상황
any	연결만 되면 수용	단일 서버 또는 서버 역할을 가리지 않을 때
read-write	기본적으로 read-write 트랜잭션을 받아야 함	쓰기 작업이 반드시 필요한 앱
read-only	기본적으로 read-write를 받지 않아야 함	조회 전용 리더 연결
primary	서버가 hot standby 모드가 아니어야 함	주 서버 역할만 구분하면 될 때
standby	서버가 hot standby 모드여야 함	복제본에만 붙이고 싶을 때
prefer-standby	standby를 먼저 찾고 없으면 아무 서버나 수용	읽기 트래픽을 standby에 우선 보내되 fallback이 필요할 때

여기서 read-write는 단순히 "primary여야 한다"와 같지 않다. PostgreSQL 공식 문서에는 이 값이 hot standby가 아니어야 할 뿐 아니라 default_transaction_read_only가 off여야 한다고 적혀 있다. 반대로 primary는 hot standby 여부만 본다.

read-write와 primary는 왜 다를까?

이 차이는 장애 조치보다 운영 정책에서 자주 드러난다. primary 서버라도 세션 기본값을 읽기 전용으로 강제할 수 있고, 그런 상태에서는 primary 조건은 만족하지만 read-write 조건은 만족하지 않는다.

host=db-a,db-b
target_session_attrs=read-write

이 설정은 "현재 바로 쓰기 가능한 서버"를 원할 때 더 안전하다. 반대로 연결 대상이 primary인지 standby인지만 구분하면 충분하고, 세션 기본값이 read only인지까지는 중요하지 않다면 primary가 더 직접적이다.

read-only와 standby도 같은 의미일까?

이 둘도 완전히 같지 않다. PostgreSQL의 Hot Standby 문서에 따르면 standby에서는 transaction_read_only가 항상 true이며, DML과 DDL을 실행할 수 없다. 그래서 대부분의 standby는 자연스럽게 read-only 조건을 만족한다.

하지만 read-only는 세션 기본값만 보는 조건이고, standby는 서버가 실제로 hot standby 모드인지 본다. 따라서 목적이 "복제본에만 붙기"라면 standby가 더 정확하고, 목적이 "실수로 쓰기 쿼리가 나가면 안 되는 세션"이라면 read-only가 더 직접적이다.

 

 

prefer-standby는 언제 유용할까?

prefer-standby는 이름 그대로 standby를 먼저 찾고, 목록 안에 standby가 없으면 다시 any처럼 동작한다. 읽기 요청을 우선 복제본으로 보내고 싶지만, 복제본 점검 중에도 애플리케이션 연결 자체는 살려야 할 때 실용적이다.

다만 이 값은 "읽기는 무조건 standby"를 보장하는 설정이 아니다. 공식 문서 설명 그대로 standby가 없으면 아무 서버나 수용하므로, 쓰기와 읽기를 강하게 분리해야 하는 경로에는 standby가 더 안전하다.

load_balance_hosts와 함께 쓰면 무엇이 달라질까?

PostgreSQL 18 문서에는 load_balance_hosts를 target_session_attrs와 함께 써서 standby 서버들만 대상으로 분산할 수 있다고 설명한다. 중요한 점은 연결이 한 번 성공하면 그 뒤 쿼리는 모두 같은 서버로 간다는 점이다.

조합	의미	주의점
target_session_attrs=standby load_balance_hosts=random	standby 중 임의 순서로 연결 시도	연결 후에는 세션 고정
target_session_attrs=read-write load_balance_hosts=random	쓰기 가능한 서버들 중 임의 순서 시도	응답 없는 노드가 있으면 connect_timeout을 같이 두는 편이 낫다
target_session_attrs=prefer-standby load_balance_hosts=random	standby 우선, 없으면 fallback 허용	standby 부재 시 primary에 붙을 수 있다

문서에는 random 사용 시 무응답 노드가 있으면 다음 노드로 넘어갈 수 있도록 적절한 connect_timeout을 함께 두는 편을 권장한다. 즉 이 옵션은 서버 역할 선택과 시도 순서를 조합하는 기능이지, 연결 후 쿼리 단위 분산까지 해결해 주는 기능은 아니다.

연결 문자열은 어떻게 적는 편이 안전할까?

host=pg-1,pg-2,pg-3
port=5432,5432,5432
dbname=app
target_session_attrs=standby
load_balance_hosts=random
connect_timeout=5

이 예시는 standby 역할의 서버만 대상으로 무작위 순서 연결을 시도한다. 반대로 쓰기 경로라면 target_session_attrs=read-write 쪽이 더 보수적이다. primary 여부만으로 충분한 경우에만 primary를 고르는 편이 명확하다.

선택 기준을 간단히 정리하면?

상황	무난한 선택	이유
쓰기 작업이 반드시 성공해야 함	read-write	hot standby 여부와 세션 기본 read-only 상태를 함께 걸러낼 수 있기 때문
복제본에만 조회를 보내고 싶음	standby	서버 역할을 직접 조건으로 거는 편이 더 분명하기 때문
복제본 우선이지만 서비스 연속성이 더 중요함	prefer-standby	standby가 없을 때 연결 실패 대신 fallback을 허용하기 때문
주 서버 역할만 구분하면 충분함	primary	세션 기본 read-only 설정까지는 보지 않기 때문

FAQ

Q. 단일 호스트만 쓰는데도 target_session_attrs가 필요할까?

필수는 아니다. 다만 단일 엔드포인트 뒤에서 역할 전환이 일어나거나, DNS가 여러 서버를 돌려주는 구조라면 의미가 생긴다. 여러 호스트 이름과 함께 쓸 때 가장 효과가 크다.

Q. prefer-standby를 쓰면 항상 읽기가 standby로 가나?

아니다. 공식 문서 기준 standby가 하나도 없으면 다시 any 모드로 시도한다. 읽기 경로를 복제본으로 강제해야 한다면 standby가 더 맞다.

Q. load_balance_hosts=random이면 쿼리마다 다른 서버로 분산되나?

그렇지 않다. 이 옵션은 연결을 시작할 때 어느 호스트를 먼저 시도할지만 바꾼다. 성공한 뒤에는 해당 연결의 모든 쿼리가 같은 서버로 간다.

정리

target_session_attrs는 PostgreSQL 다중 호스트 연결에서 "붙을 수 있는 서버"가 아니라 "붙어도 되는 서버"를 고르는 옵션이다. 2026년 7월 15일 기준 PostgreSQL 18 공식 문서만 기준으로 보면, 쓰기 경로에는 read-write, 복제본 강제에는 standby, 복제본 우선 fallback 허용에는 prefer-standby가 가장 이해하기 쉽다.

판단 기준은 세 가지면 충분하다. 첫째, primary/standby 역할을 구분하고 싶은지, 실제 쓰기 가능 여부까지 확인하고 싶은지 나눈다. 둘째, standby가 없을 때 실패시킬지 fallback을 허용할지 정한다. 셋째, 시도 순서를 섞고 싶다면 load_balance_hosts=random과 connect_timeout을 함께 검토한다.

참고 자료

• PostgreSQL 18 공식 문서: libpq connection parameters
• PostgreSQL 18 공식 문서: Hot Standby