OpenProxy 설정 레퍼런스
버전: 1.1.3
1. 설정 파일 구조
OpenProxy는 TOML 형식의 설정 파일을 사용합니다. 기본 파일 이름은 openproxy.toml이며, 실행 시 경로를 지정할 수 있습니다.
설정 파일은 다음 섹션으로 구성됩니다.
[general]
전역 설정 (네트워크, 타임아웃, 관리자 계정 등)
[general.etcd]
etcd 연동 설정 (선택)
[general.virtual_router]
VRRP / VIP 설정 (선택)
[general.default_pool]
글로벌 Pool (선택)
[pools.<name>]
풀 설정. <name>은 클라이언트가 접속할 데이터베이스 이름
[pools.<name>.users.<n>]
풀별 사용자 설정 (<n>은 0부터 시작하는 인덱스)
[pools.<name>.shards.<n>]
풀별 서버 연결 설정 (<n>은 0부터 시작하는 인덱스)
2. [general] 섹션
네트워크
host
"0.0.0.0"
수신 IP 주소. 0.0.0.0은 모든 인터페이스에서 수신
port
5432
수신 포트. PgBouncer와 동일하게 6432를 관례적으로 사용
관리자 계정
admin_username
"admin"
관리자 콘솔 접속 계정
admin_password
"admin"
관리자 콘솔 접속 패스워드. 운영 환경에서는 반드시 변경
커넥션 및 타임아웃
connect_timeout
1000 (ms)
서버 연결 수립 대기 시간. 초과 시 해당 서버를 일시 차단
idle_timeout
600000 (ms)
유휴 서버 연결 유지 시간. 초과 시 연결 종료
server_lifetime
3600000 (ms)
서버 연결 최대 유지 시간. 초과 시 유휴 연결 종료
idle_client_in_transaction_timeout
0 (ms)
트랜잭션 내 유휴 클라이언트 대기 시간. 0은 무제한
ban_time
60 (s)
오류 발생 서버를 일시 차단하는 시간
shutdown_timeout
60000 (ms)
종료 시 진행 중인 트랜잭션 완료 대기 시간
healthcheck_timeout
1000 (ms)
서버 헬스체크 타임아웃
healthcheck_delay
30000 (ms)
헬스체크 주기
성능
worker_threads
4
Tokio 비동기 워커 스레드 수. PostgreSQL과 같은 노드에서 실행하는 경우 CPU 코어 수의 절반 권장
server_round_robin
true
서버 선택 시 라운드로빈 사용 여부
TLS (클라이언트 연결)
tls_certificate
없음
TLS 인증서 파일 경로. 설정 시 클라이언트와의 TLS 연결 활성화
tls_private_key
없음
TLS 개인 키 파일 경로
TLS (서버 연결)
server_tls
false
PostgreSQL 서버와의 TLS 연결 사용 여부
verify_server_certificate
false
서버 TLS 인증서 검증 여부
3. [general.etcd] 섹션
etcd 연동을 설정합니다. etcd를 사용하지 않는 경우 이 섹션을 설정 파일에서 제거합니다.
enabled
예
true
etcd 연동 활성화 여부
endpoints
예
—
etcd 엔드포인트 목록. 예: ["192.168.1.1:2379", "192.168.1.2:2379"]
patroni_scope
예
—
Patroni 클러스터 scope. Patroni의 PATRONI_SCOPE 환경변수와 일치해야 함
patroni_namespace
아니오
"/service"
Patroni DCS namespace. Patroni의 PATRONI_NAMESPACE 환경변수와 일치해야 함
username
아니오
없음
etcd 인증 사용자 이름
password
아니오
없음
etcd 인증 패스워드
⚠️ 주의:
enabled변경 시 프로세스 재시작 필요
enabled값을 변경하면 설정 파일 자동 reload가 변경을 감지하더라도 etcd 연동이 활성화되거나 비활성화되지 않습니다. 반드시 OpenProxy 프로세스를 재시작해야 합니다.
4. [general.virtual_router] 섹션
VRRP 기반 가상 IP(VIP)를 설정합니다. 여러 OpenProxy 인스턴스에 VIP를 적용할 때 사용합니다. VIP가 필요 없는 경우 이 섹션을 설정 파일에서 제거합니다.
interface
예
네트워크 인터페이스 이름. 예: "eth0"
router_id
예
VRRP 라우터 ID (1~255). 동일 네트워크 내 다른 VRRP 그룹과 중복되지 않아야 함
priority
예
VRRP 우선순위 (1~255). 값이 높을수록 VIP를 우선 소유
advert_int
예
VRRP 광고 패킷 전송 주기 (초)
vip_addresses
예
가상 IP 목록. CIDR 표기법 사용. 예: ["192.168.1.100/24"]
pre_promote_script
아니오
MASTER 승격 직전 실행할 스크립트 경로
pre_demote_script
아니오
MASTER 강등 직전 실행할 스크립트 경로
unicast_peers
아니오
유니캐스트 VRRP를 사용하는 경우 상대 노드 IP 목록
참고: VRRP 기능은
CAP_NET_ADMIN,CAP_NET_RAW권한을 필요로 합니다. systemd 서비스 파일의AmbientCapabilities설정을 확인하십시오.
참고:
virtual_router설정은 etcd에 동기화되지 않습니다. 각 노드의 설정 파일에서 개별적으로 관리해야 합니다.
5. [general.default_pool] 섹션
명시적으로 Pool로 등록되지 않은 사용자 이름 - DB 이름 쌍을 가진 사용자 요청을 처리할 글로벌 Connection Pool을 정의합니다. 사용자 이름과 비밀번호를 정의할 수 없으므로 PostgreSQL 에 정의된 사용자 정보를 가져와 클라이언트 요청을 인증하는 auth_passthrough 방식만을 지원합니다. 정의한 auth_query 는 이 Pool의 첫번째Shard에 정의한 데이터베이스에서 실행됩니다.
기타 Users, Shards 설정은 이름이 정의된 Explicit Pool 에서의 설정과 동일합니다. 사용자 정의는 첫번째 사용자 정의를 참조하며 pool_size, statement_timeout 정의만을 참조합니다.
인증
auth_query
—
사용자 이름과 패스워드 해시를 가져올 쿼리.
예: SELECT usename, password FROM pg_shadow WHERE usename = '$1'
auth_query_user
—
auth_query 를 실행할 사용자 이름
auth_query_password
—
auth_query 를 실행할 사용자 비밀번호
6. [pools.<name>] 섹션
풀을 정의합니다. <name>은 클라이언트가 -d 옵션으로 지정하는 데이터베이스 이름이 됩니다. 풀은 여러 개 정의할 수 있습니다.
풀링 모드
pool_mode
"transaction"
풀링 모드. "transaction" 또는 "session"
인증
auth_type
"md5"
클라이언트 인증 방식. "md5" 또는 "scram-sha-256"
읽기/쓰기 분리
query_parser_enabled
false
SQL 파싱을 통한 자동 역할 결정 활성화
query_parser_read_write_splitting
false
읽기/쓰기 분리 활성화. query_parser_enabled = true 필요
primary_reads_enabled
false
읽기 쿼리 대상에 primary 포함 여부
default_role
"any"
역할 결정 불가 시 기본 라우팅 대상. "primary", "replica", "any"
로드 밸런싱
load_balancing_mode
"random"
로드 밸런싱 방식. "random" 또는 "least_outstanding_connections"
prepared_statements_cache_size
0
풀 단위의 Prepared Statements를 저장할 Cache 크기. 0인 경우 클라이언트 별로 Prepared Statements를 관리함.
타임아웃 (풀별 오버라이드)
[general] 섹션의 값을 풀별로 오버라이드할 수 있습니다. 설정하지 않으면 [general]의 값을 따릅니다.
connect_timeout
서버 연결 수립 대기 시간 (ms)
idle_timeout
유휴 서버 연결 유지 시간 (ms)
server_lifetime
서버 연결 최대 유지 시간 (ms)
7. [pools.<name>.users.<n>] 섹션
풀에 접속할 수 있는 사용자를 정의합니다. <n>은 0부터 시작합니다. 사용자는 여러 명 정의할 수 있습니다.
username
예
—
클라이언트가 사용하는 계정 이름. 지정되지 않은 사용자 이름에 대한 연결을 허용하고자 하는 경우 와일드카드 문자열 * 을 지정한 사용자 정의를 생성합니다.
password
예
—
클라이언트 인증 패스워드
pool_size
예
—
이 사용자를 위해 유지할 서버 연결 최대 수
server_username
아니오
username과 동일
PostgreSQL 서버에 접속하는 계정 이름. 클라이언트 계정과 다를 수 있음
server_password
아니오
—
PostgreSQL 서버 접속 패스워드
min_pool_size
아니오
0
유지할 서버 연결 최소 수
statement_timeout
아니오
0 (ms)
쿼리 실행 제한 시간. 0은 무제한
pool_mode
아니오
풀의 pool_mode
사용자별 풀링 모드 오버라이드
pool_size 계산 방법
(PostgreSQL max_connections - 슈퍼유저 연결 수) / 풀 수예:
max_connections = 100, 풀 2개인 경우 →pool_size = 45
8. [pools.<name>.shards.<n>] 섹션 — 서버 연결 설정
OpenProxy가 연결할 PostgreSQL 서버 목록을 정의합니다. <n>은 0부터 시작합니다. 샤딩을 사용하지 않는 일반 환경에서는 shards.0 하나만 정의합니다.
servers
예
PostgreSQL 서버 목록. 각 항목은 ["호스트", 포트, "역할"] 형식
database
예
접속할 PostgreSQL 데이터베이스 이름
use_patroni
아니오
Patroni 연동 활성화 여부. true로 설정하면 역할을 Patroni가 관리
patroni_port
아니오
Patroni REST API 포트. 기본값: 8008
servers 역할 값
"primary"
쓰기 서버로 고정
"replica"
읽기 서버로 고정
"Auto"
Patroni 연동 시 사용. Patroni가 역할을 자동으로 결정
Patroni 연동 없이 직접 역할 지정
Patroni 연동 (역할 자동 감지)
9. 설정 예시
파일 단독 모드 (standalone)
읽기/쓰기 분리 없이 단일 primary에만 연결하는 가장 단순한 구성입니다.
etcd 연동 모드 (HA)
Patroni HA 클러스터와 연동하여 읽기/쓰기 분리 및 자동 Failover를 사용하는 구성입니다.
Global Pool 예시
[pools.{pool_name}] 형태로 정의되지 않은 사용자 요청을 처리할 Global 레벨의 Default Pool을 정의하는 예시입니다. Default Pool의 경우 임의 사용자에 대한 비밀번호를 설정할 수 없어 인증을 PostgreSQL로 위임하므로 auth_query 관련 설정이 반드시 필요합니다.
또한 scram-sha-256 타입 인증을 사용하면서 auth_query 를 함께 사용하는 경우는 OpenProxy에서 PostgreSQL로 접속하기 위한 패스워드를 알 수 없으므로 PostgreSQL 로의 연결이 반드시 trust 레벨로 설정되어야 합니다.
Wildcard User 예시
정의된 Pool 밑에 모든 사용자 요청을 처리할 Wildcard * 사용자를 생성하는 예시입니다. 마찬가지로 auth_query 정의가 필요하며 해당 쿼리는 첫번째 shards 의 데이터베이스에서 실행됩니다.
또한 scram-sha-256 타입 인증을 사용하면서 auth_query 를 함께 사용하는 경우는 OpenProxy에서 PostgreSQL로 접속하기 위한 패스워드를 알 수 없으므로 PostgreSQL 로의 연결이 반드시 trust 레벨로 설정되어야 합니다.
Last updated