Ruby 커넥터를 사용하여 Aurora DSQL 클러스터에 연결

Ruby용 Aurora DSQL 커넥터는 Ruby 애플리케이션을 Amazon Aurora DSQL 클러스터에 연결하기 위한 IAM 인증을 통합하는 pg를 기반으로 구축된 .NET 커넥터입니다.

이 커넥터는 토큰 생성, SSL 구성 및 연결 풀링을 처리하므로 애플리케이션 로직에 집중할 수 있습니다.

커넥터 정보

Amazon Aurora DSQL에는 기존 Ruby PostgreSQL 드라이버가 기본적으로 지원하지 않는 시간 제한 토큰을 사용한 IAM 인증이 필요합니다. Ruby용 Aurora DSQL 커넥터는 IAM 토큰 생성을 처리하는 pg gem 위에 인증 계층을 추가하여 기존 pg 워크플로를 변경하지 않고도 Aurora DSQL에 연결할 수 있도록 합니다.

Aurora DSQL 인증이란 무엇인가요?

Aurora DSQL에서 인증에는 다음이 포함됩니다.

Ruby용 Aurora DSQL 커넥터는 이러한 요구 사항을 이해하고 연결을 설정할 때 IAM 인증 토큰을 자동으로 생성합니다.

특성

애플리케이션 예시

전체 예제는 GitHub의 예제 애플리케이션을 참조하세요.

빠른 시작 설명서

요구 사항

설치

Gemfile에 추가합니다.

gem "aurora-dsql-ruby-pg"

또는 직접 설치합니다.

gem install aurora-dsql-ruby-pg

사용법

풀 연결

require "aurora_dsql_pg"

# Create a connection pool with OCC retry enabled
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  occ_max_retries: 3
)

# Read
pool.with do |conn|
  result = conn.exec("SELECT 'Hello, DSQL!'")
  puts result[0]["?column?"]
end

# Write — you must wrap writes in a transaction
pool.with do |conn|
  conn.transaction do
    conn.exec_params("INSERT INTO users (id, name) VALUES (gen_random_uuid(), $1)", ["Alice"])
  end
end

pool.shutdown

단일 연결

간단한 스크립트의 경우 또는 연결 풀링이 필요하지 않은 경우:

conn = AuroraDsql::Pg.connect(host: "your-cluster.dsql.us-east-1.on.aws")
conn.exec("SELECT 1")
conn.close

고급 사용

호스트 구성

커넥터는 전체 클러스터 엔드포인트(리전 자동 감지)와 클러스터 ID(리전 필수)를 모두 지원합니다.

# Full endpoint (region auto-detected)
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws"
)

# Cluster ID (region required)
pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster-id",
  region: "us-east-1"
)

AWS 프로필

자격 증명에 대한 AWS 프로파일 지정:

pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  profile: "production"
)

연결 문자열 형식

커넥터는 다음의 PostgreSQL 연결 문자열 형식을 지원합니다.

postgres://[user@]host[:port]/[database][?param=value&...]
postgresql://[user@]host[:port]/[database][?param=value&...]

지원되는 쿼리 파라미터: region, profile, tokenDurationSecs.

# Full endpoint with profile
pool = AuroraDsql::Pg.create_pool(
  "postgres://admin@cluster.dsql.us-east-1.on.aws/postgres?profile=dev"
)

OCC 재시도

Aurora DSQL은 낙관적 동시성 제어(OCC)를 사용합니다. 두 개의 트랜잭션이 동일한 데이터를 수정할 경우, 먼저 커밋된 트랜잭션이 우선권을 가지며 두 번째 트랜잭션은 OCC 오류를 수신합니다.

OCC 재시도가 옵트인되었습니다. pool.with에서 지수 백오프 및 지터를 사용하여 자동 재시도를 활성화하려면 풀을 생성할 때 occ_max_retries를 설정합니다.

pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  occ_max_retries: 3
)

pool.with do |conn|
  conn.transaction do
    conn.exec_params("UPDATE accounts SET balance = balance - $1 WHERE id = $2", [100, from_id])
    conn.exec_params("UPDATE accounts SET balance = balance + $1 WHERE id = $2", [100, to_id])
  end
end

개별 직접 호출에 대한 재시도를 건너뛰려면 retry_occ: false를 전달합니다.

pool.with(retry_occ: false) do |conn|
  conn.exec("SELECT 1")
end

구성 옵션

create_pool은 ConnectionPool.new에 직접 전달하는 옵션 해시가 있는 pool: 키워드도 허용합니다. pool:을 생략하는 경우 커넥터의 기본값은 {size: 5, timeout: 5}입니다. 제공하는 키는 특정 기본값만 재정의합니다.

pool = AuroraDsql::Pg.create_pool(
  host: "your-cluster.dsql.us-east-1.on.aws",
  pool: { size: 10, timeout: 10 }
)

Authentication

커넥터는 AWS 자격 증명을 사용해 토큰을 생성하여 Aurora DSQL 인증을 자동으로 처리합니다. AWS 리전을 제공하지 않으면 커넥터가 호스트 이름에서 리전을 구문 분석합니다.

Aurora DSQL의 인증에 대한 자세한 내용은 Aurora DSQL에 대한 인증 및 권한 부여 섹션을 참조하세요.

관리자와 일반 사용자