데이터베이스 읽기 복제본

데이터베이스 읽기 복제본 (Database Read Replica)

LiteLLM 프록시는 읽기 전용 쿼리를 별도의 데이터베이스 엔드포인트로 라우팅하고, 쓰기는 계속 프라이머리로 보낼 수 있어요. 별도의 읽기/쓰기 엔드포인트를 노출하는 Aurora 스타일 클러스터에서 유용한데, 읽기를 리더로 보내면 라이터를 트랜잭션 워크로드에 비워둘 수 있어요.

출처: 문서

본문

빠른 시작 (Quick start)

기존 DATABASE_URL 옆에 DATABASE_URL_READ_REPLICA를 설정하세요:

export DATABASE_URL=postgresql://user:***@writer.db.example.com:5432/litellm
export DATABASE_URL_READ_REPLICA=postgresql://user:***@reader.db.example.com:5432/litellm

프록시는 시작 시 환경 변수를 자동 감지하고 내부 Prisma 클라이언트를 두 엔드포인트 사이에서 트래픽을 분할하는 라우팅 모드로 전환해요. DATABASE_URL_READ_REPLICA가 설정되지 않으면 프록시는 단일 데이터베이스 동작을 계속 사용해요. 추가 구성은 필요 없어요.

어떤 것이 라우팅되는가 (What gets routed)

작업	대상
find_first, find_many, find_unique (및 _or_raise 변형)	리더
count, group_by	리더
query_raw, query_first	리더
create, update, upsert, delete, update_many, delete_many	라이터
execute_raw	라이터
트랜잭션 (tx, batch_)	라이터

코드에서 시작되는 읽기(예: 가상 키 조회, 팀 멤버십, 지출 쿼리)는 호출 지점 변경 없이 리더로 전달돼요. 라우팅 래퍼가 모델별 액션 접근자를 가로채고 메서드별로 백엔드를 선택해요.

리더 성능 저하 (Reader degradation)

시작 시 리더 엔드포인트에 도달할 수 없으면 프록시는 경고를 기록하고 시작 실패 대신 읽기를 라이터로 폴백해요:

Failed to connect to read replica DB: <error>. Falling back to the writer for reads until the reader is reachable.

재연결 주기 중에 리더가 실패해도 같은 폴백이 적용돼요. 다음 성공적인 리더 재생성이 성능 저하 플래그를 해제하고 읽기가 다시 리더에 도달하기 시작해요.

즉, 읽기 복제본 라우팅을 활성화해도 가용성이 절대 줄어들지 않아요. 최악의 경우 단일 데이터베이스 성능으로 저하돼요.

토큰 기반 데이터베이스 인증 (Token-based database authentication)

IAM_TOKEN_DB_AUTH=True(AWS RDS IAM) 또는 AZURE_POSTGRESQL_AUTH=True(Microsoft Entra ID)일 때 라이터와 리더가 서로 독립적으로 각자 만료 전에 토큰을 갱신해요. 리더를 단일 DATABASE_URL_READ_REPLICA로 또는 컴포넌트 변수(DATABASE_HOST_READ_REPLICA, DATABASE_USER_READ_REPLICA 등)에서 조립해 제공할 수 있어요. 토큰 갱신 경로가 결과 리더 URL을 다시 파싱하므로 시작 후 토큰만 회전해요.

AWS에서는 이게 Aurora의 리더 엔드포인트와 자연스럽게 어울려요. 리더 엔드포인트는 클러스터의 리더 인스턴스로 해석돼요. Azure에서는 Azure Database for PostgreSQL Flexible Server의 읽기 복제본과 어울려요.

Kubernetes / Helm

공식 Helm 차트는 리더 URL을 연결하는 두 가지 방법을 노출해요.

Kubernetes 시크릿에서 (권장)

리더 URL에 자격 증명이 포함되면 기존 db.secret.name Kubernetes 시크릿에서 db.secret.readReplicaUrlKey로 소싱하세요. 이렇게 하면 URL이 렌더링된 pod 스펙과 Helm 릴리스 시크릿에 남지 않아요.

db:
  useExisting: true
  secret:
    name: postgres
    usernameKey: username
    passwordKey: password
    # Add the reader URL to the same secret under any key, then reference it:
    readReplicaUrlKey: read-url

일반 텍스트 값 (Plaintext value)

자격 증명 없는 URL(예: IAM_TOKEN_DB_AUTH 또는 AZURE_POSTGRESQL_AUTH가 런타임에 비밀번호를 공급)용으로 db.readReplicaUrl이 동작해요:

db:
  readReplicaUrl: "postgresql://[email protected]:5432/litellm"

URL에 비밀번호가 포함되면 이 형태를 피하세요. 값이 pod 스펙과 Helm 릴리스 시크릿으로 렌더링되기 때문이에요.

Docker Compose

서비스에 환경 변수를 추가하세요:

services:
  litellm:
    environment:
      DATABASE_URL: postgresql://user:***@writer:5432/litellm
      DATABASE_URL_READ_REPLICA: postgresql://user:***@reader:5432/litellm

언제 활성화할까 (When to enable it)

읽기 복제본 라우팅은 다음 경우에 가장 유용해요:

Aurora(또는 리더 엔드포인트가 있는 다른 관리형 Postgres)를 쓰고 지출/팀/키 조회를 라이터에서 오프로드하려는 경우.
읽기 트래픽이 지배적이고 라이터 CPU/연결이 제약받는 경우.
지리적 읽기 지역성(리더가 프록시에 더 가까움)을 원하는 경우.

다음 경우에는 유용하지 않아요:

프라이머리와 복제본이 같은 물리 엔드포인트인 경우.
복제본 없이 단일 노드 Postgres를 실행하는 경우.
복제 지연이 앱의 일관성 가정을 무효화하는 경우. 모든 읽기가 리더로 라우팅되는데, 쓰기 직후에 이어지는 읽기도 포함해요.

복제 지연 (Replication lag)

프록시는 리더 엔드포인트에 대해 read-after-write 일관성을 구현하지 않아요. 복제 지연이 의미 있는(>100ms) 상황에서 쓰고 나서 같은 행을 즉시 읽는 플로우가 있다면, 그 읽기는 오래된 데이터를 볼 수 있어요. 새 쓰기에 강한 일관성이 필요한 코드는 라이터를 통한 query_raw를 사용하거나 트랜잭션 범위 읽기에 의존하세요.

환경 변수	설명
DATABASE_URL	라이터 연결 URL (필수).
DATABASE_URL_READ_REPLICA	리더 연결 URL (선택). 설정되지 않으면 모든 읽기가 라이터로 감.
IAM_TOKEN_DB_AUTH	True면 라이터와 리더가 AWS RDS IAM 토큰을 자동 갱신.
AZURE_POSTGRESQL_AUTH	True면 라이터와 리더가 Microsoft Entra ID 토큰을 자동 갱신.

전체 목록은 environment variables - Reference 참고.

데이터베이스 읽기 복제본