Ctrlk
ENGDocs Home
For the complete documentation index, see llms.txt. This page is also available as Markdown.
Export as PDF

Openproxy 사용 설명서

OpenProxy 사용 설명서

버전: 1.1.3

1. Synopsis

openproxy [config_file]
openproxy show [--full] [--format toml|json] [--section <섹션명>]
openproxy edit [--set <key>=<value>]
openproxy encode [password]
openproxy --force-config-file [config_file]
openproxy [--log-target file|stdout|both] [--log-level trace|debug|info|warn|error]
          [--log-dir <디렉토리>] [--max-logfile-num <개수>] [--log-format text|structured|debug]
openproxy --version
openproxy --help

2. 개요

OpenProxy는 Rust로 작성된 PostgreSQL 커넥션 풀러 및 프록시입니다. 애플리케이션은 OpenProxy를 PostgreSQL 서버처럼 연결하며, OpenProxy가 실제 서버 연결을 관리합니다.

주요 기능

  • 커넥션 풀링: 새 연결 생성 비용을 줄여 성능을 개선합니다.

  • 읽기/쓰기 분리: 쿼리를 자동으로 분석하여 쓰기는 primary, 읽기는 replica로 라우팅합니다.

  • 로드 밸런싱: 여러 replica 간에 읽기 쿼리를 분산합니다.

  • 자동 Failover: OpenSQL 에서 primary가 변경되면 자동으로 감지하여 새 primary로 연결합니다.

  • etcd 연동: etcd에 설정을 저장하고 여러 OpenProxy 인스턴스 간에 설정을 공유합니다.

  • VRRP / VIP: 여러 OpenProxy 인스턴스 앞단에 가상 IP를 제공하여 고가용성을 구성합니다.

3. 핵심 개념

3.1 커넥션 풀링 모드

OpenProxy는 두 가지 풀링 모드를 지원합니다.

트랜잭션 풀링 (transaction) — 권장

트랜잭션이 시작될 때 서버 연결을 할당하고, 트랜잭션이 끝나면 즉시 풀로 반환합니다. 하나의 서버 연결을 여러 클라이언트가 순차적으로 재사용하므로 연결 수를 크게 줄일 수 있습니다.

단, 트랜잭션 외부에서 SET 명령어나 임시 테이블을 사용하는 경우 의도하지 않은 동작이 발생할 수 있습니다.

세션 풀링 (session)

클라이언트가 연결된 동안 서버 연결이 전용으로 유지됩니다. SET 명령, 준비된 구문, 임시 테이블 등 세션 상태를 사용하는 애플리케이션에 적합합니다. 단, 서버 연결 수 절감 효과가 트랜잭션 풀링에 비해 작습니다.

3.2 읽기/쓰기 분리 (Query Router)

query_parser_enabled = true와 query_parser_read_write_splitting = true를 설정하면 OpenProxy가 SQL 쿼리를 파싱하여 자동으로 역할을 결정합니다.

  • SELECT → replica로 라우팅

  • INSERT, UPDATE, DELETE, DDL → primary로 라우팅

  • 트랜잭션 내부 쿼리 → 트랜잭션 시작 시점에 결정된 역할 유지

primary_reads_enabled = true로 설정하면 replica가 없거나 부하 분산이 필요한 경우 primary도 읽기 대상에 포함됩니다.

3.3 운영 모드

OpenProxy는 두 가지 운영 모드를 지원합니다.

파일 단독 모드

설정 파일(openproxy.toml)만 사용합니다. 설정 파일이 변경되면 5초 주기로 자동 감지하여 reload합니다. 단일 서버 환경이나 etcd 없이 운영하는 경우에 적합합니다.

etcd 연동 모드 (HA)

설정을 etcd에 저장하고 여러 노드가 공유합니다. etcd의 설정이 변경되면 모든 OpenProxy 인스턴스에 자동으로 반영됩니다. Patroni와 동일한 etcd 클러스터를 사용하여 primary/replica 역할을 자동으로 감지합니다.

3.4 설정 우선순위

설정이 여러 곳에 있을 경우 다음 우선순위를 따릅니다.

--force-config-file 옵션을 사용하면 etcd를 무시하고 설정 파일만 사용합니다.

3.5 VRRP / VIP

여러 OpenProxy 인스턴스를 운영할 때 클라이언트가 항상 활성 인스턴스에 연결할 수 있도록 가상 IP(VIP)를 제공합니다. VRRP 프로토콜을 사용하여 인스턴스 간에 VIP 소유권을 협상하며, 활성 인스턴스가 다운되면 다른 인스턴스가 VIP를 인수합니다.

VRRP 기능을 사용하려면 CAP_NET_ADMIN, CAP_NET_RAW 권한이 필요합니다. OpenSQL 에서 제공하는 systemd 서비스 파일을 사용하면 해당 권한이 자동으로 부여됩니다.

4. 빠른 시작

파일 단독 모드

  1. 설정 파일을 작성합니다.

  1. OpenProxy를 실행합니다.

  1. 접속을 확인합니다.

etcd 연동 모드 (HA)

  1. 설정 파일에 etcd 섹션을 추가합니다.

  1. OpenProxy를 실행합니다.

etcd에 연결되면 설정이 etcd에 저장되고 이후부터는 etcd를 통해 관리됩니다.

5. systemd 서비스 등록

운영 환경에서는 systemd 서비스로 등록하여 실행하는 것을 권장합니다. 서버 재부팅 시 자동으로 시작되고, 비정상 종료 시 자동으로 재시작됩니다.

서비스 파일 위치: /etc/systemd/system/openproxy.service

서비스 등록 및 시작

서비스 중지 및 재시작

6. 실행 옵션

openproxy [config_file]

OpenProxy를 시작합니다. config_file을 지정하지 않으면 현재 디렉토리의 openproxy.toml을 사용합니다.

openproxy show

현재 로드된 설정을 출력하고 종료합니다. 서비스를 시작하지 않습니다.

설정 파일 경로를 지정하는 경우, 경로는 반드시 서브커맨드 앞에 위치해야 합니다.

openproxy edit

설정을 편집하고 저장합니다.

설정 파일 경로를 지정하는 경우, 경로는 반드시 서브커맨드 앞에 위치해야 합니다.

etcd가 활성화된 경우, 변경 내용은 etcd에 저장되며 설정 파일은 수정되지 않습니다. 단, virtual_router 설정은 etcd에 저장되지 않으므로 설정 파일에서 직접 수정해야 합니다.

openproxy encode

데이터베이스 사용자 비밀번호를 SCRAM-SHA-256 서버에서 인식할 수 있는 형태로 암호화합니다.

출력되는 결과값은 openproxy.toml 파일의 사용자 Password로 사용할 수 있습니다. auth_type 값이 scram-sha-256 형태로 지정된 경우에만 올바르게 동작합니다.

PostgreSQL에 연결하기 위한 server_password 값으로는 사용할 수 없습니다.

--force-config-file

etcd가 활성화된 환경에서도 설정 파일만 사용합니다. etcd 연결 문제 발생 시 임시 우회 수단으로 사용합니다.

로그 옵션

옵션
기본값
설명

--log-target

both

로그 출력 대상. file (파일만), stdout (표준출력만), both (둘 다)

--log-level

info

로그 레벨. trace, debug, info, warn, error

--log-dir

logs

로그 파일 저장 디렉토리. log-target이 file 또는 both일 때 사용

--max-logfile-num

5

로그 파일 최대 보관 개수. 로그 파일은 매일 자정에 새로 생성되며, 보관 개수 초과 시 오래된 파일부터 삭제

--log-format

text

로그 출력 형식. text (사람이 읽기 쉬운 형식), structured (JSON 등 구조화 형식), debug

7. 관리자 콘솔

OpenProxy는 관리자 콘솔을 제공합니다. PostgreSQL 클라이언트로 openproxy 데이터베이스에 접속하여 사용합니다.

접속 방법

admin_username과 admin_password는 설정 파일의 general.admin_username, general.admin_password에 정의된 값입니다.

SHOW 명령어

명령어
설명

SHOW POOLS

각 풀의 커넥션 수, 대기 클라이언트 수 등 풀 상태

SHOW CLIENTS

현재 연결된 클라이언트 목록

SHOW SERVERS

현재 열려 있는 서버 연결 목록

SHOW STATS

쿼리 수, 바이트 수, 응답 시간 등 통계

SHOW DATABASES

설정된 풀(데이터베이스) 목록

SHOW USERS

설정된 사용자 목록

SHOW CONFIG

현재 로드된 설정 값

SHOW LISTS

내부 오브젝트 개수 통계

SHOW BANS

일시 차단된 서버 목록

SHOW VERSION

OpenProxy 버전 정보

SHOW HELP

사용 가능한 명령어 목록

제어 명령어

명령어
설명

RELOAD

설정을 다시 로드합니다. etcd 활성 시 Patroni 역할만 갱신합니다.

PAUSE [db, user]

지정한 풀(또는 전체)의 새 쿼리 수신을 중지합니다. 진행 중인 트랜잭션은 완료를 기다립니다.

RESUME [db, user]

PAUSE로 중지된 풀을 재개합니다.

SHUTDOWN

OpenProxy를 종료합니다.

SET 명령어

일부 설정 값을 런타임에 변경합니다.

8. 제약사항

etcd.enabled 변경 시 프로세스 재시작 필요

general.etcd.enabled 값을 false에서 true로, 또는 true에서 false로 변경하는 경우 반드시 OpenProxy 프로세스를 재시작해야 합니다.

파일 기반 설정 자동 reload가 변경을 감지하더라도, etcd watch 태스크는 프로세스 시작 시 최초 1회만 활성화됩니다. 런타임 중 enabled 값을 변경해도 etcd 연동이 활성화되거나 비활성화되지 않습니다.

etcd 활성 시 RELOAD 동작 차이

etcd가 활성화된 상태(enabled = true)에서 RELOAD 명령 또는 SIGHUP 시그널을 보내면 설정 전체를 재로드하는 대신 Patroni 역할 정보만 갱신합니다.

etcd 연동 환경에서 설정을 변경하려면 openproxy edit 명령을 사용하거나 etcd에 직접 값을 저장해야 합니다.

virtual_router는 etcd 동기화 대상에서 제외

[general.virtual_router] 설정은 노드마다 다를 수 있으므로(interface 이름, priority 등) etcd에 저장되지 않습니다. 해당 설정은 각 노드의 설정 파일에서 직접 관리해야 합니다.

PreviousOpenproxyNextOpenProxy 설정 레퍼런스

Last updated