연결 옵션 지정

개요

이 섹션에서는 Ruby 운전자 에서 사용할 수 있는 MongoDB 연결 및 인증 옵션에 대해 설명합니다. 연결 URI(연결 문자열 이라고도 함)를 사용하거나 Mongo::Client 생성자에 인수를 전달하여 연결을 구성할 수 있습니다.

연결 URI 사용

연결 URI를 Mongo::Client 생성자에 전달하는 경우 문자열에 연결 옵션을 <name>=<value> 쌍으로 포함할 수 있습니다. 다음 예시에서 연결 URI에는 값이 60000인 connectTimeoutMS 옵션과 값이 true인 tls 옵션이 포함되어 있습니다.

uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true"client = Mongo::Client.new(uri)

Mongo::Client 사용

연결 옵션을 연결 URI에 포함하는 대신 Mongo::Client 생성자에 인수로 전달할 수 있습니다. 이러한 방식으로 연결을 구성하면 런타임에 설정을 변경하고 컴파일 중에 오류를 포착하기가 더 쉬워집니다. 다음 예시 Mongo::Client 생성자를 사용하여 연결 옵션을 설정하다 방법을 보여 줍니다.

uri = "mongodb://<hostname>:<port>"client = Mongo::Client.new(uri, connect_timeout: 60000, ssl: true)

연결 옵션

다음 섹션에서는 Ruby 운전자 에서 사용할 수 있는 연결 옵션에 대해 설명합니다.

네트워크 압축

연결 옵션	설명
:compressors	사용할 수 있는 압축기 목록(선호도 순). 드라이버는 서버에서도 지원되는 첫 번째 압축기를 선택합니다. 현재 드라이버는 `zstd`, `snappy`, `zlib`만 지원합니다. 데이터 유형: `Array<String>` 기본값: 없음 클라이언트 예시: `compressors: ['snappy', 'zstd', 'zlib']` 연결 URI 예시: `compressors=snappy,zstd,zlib`
:zlib_compression_level	압축을 사용하는 경우 사용할 zlib 압축 수준입니다. 이 옵션은 `-1` 에서 `9`사이의 정수 값을 허용합니다. - -1: zlib은 기본값 압축 수준(일반적으로 `6`)을 사용합니다. - 0: 압축이 없습니다. - 1: 속도는 가장 빠르지만 압축률은 가장 낮습니다. - 9: 압축률은 가장 높지만 속도가 가장 느립니다. 자세한 내용은 Ruby의 zlib 모듈 도큐먼트를 참조하십시오. 데이터 유형: `Integer` 기본값: `None` 클라이언트 예시: `zlib_compression_level: 3` 연결 URI 예시: `zlibCompressionLevel=3`

연결 옵션

설명

:compressors

사용할 수 있는 압축기 목록(선호도 순). 드라이버는 서버에서도 지원되는 첫 번째 압축기를 선택합니다. 현재 드라이버는 zstd, snappy, zlib만 지원합니다.

데이터 유형: Array<String>
기본값: 없음
클라이언트 예시: compressors: ['snappy', 'zstd', 'zlib']
연결 URI 예시: compressors=snappy,zstd,zlib

:zlib_compression_level

압축을 사용하는 경우 사용할 zlib 압축 수준입니다. 이 옵션은 -1 에서 9사이의 정수 값을 허용합니다.

- -1: zlib은 기본값 압축 수준(일반적으로 6)을 사용합니다.
- 0: 압축이 없습니다.
- 1: 속도는 가장 빠르지만 압축률은 가장 낮습니다.
- 9: 압축률은 가장 높지만 속도가 가장 느립니다.

자세한 내용은 Ruby의 zlib 모듈 도큐먼트를 참조하십시오.

데이터 유형: Integer
기본값: None
클라이언트 예시: zlib_compression_level: 3
연결 URI 예시: zlibCompressionLevel=3

시간 초과

연결 옵션	설명
:connect_timeout	예외가 발생하기 전에 소켓 연결을 설정하기 위해 대기할 시간(초) 입니다. 이 타임아웃은 SRV DNS 기록 해결에도 사용됩니다. `nil` 과 `0` 은 타임아웃이 없음을 의미합니다. 유효하지 않은 타임아웃 값(예: 음수 값 또는 숫자 아닌 값)을 전달하면 클라이언트 생성이 오류로 실패합니다. 데이터 유형: `Float` 기본값: `10.0` 클라이언트 예시: `connect_timeout: 10.0` 연결 URI 예시: `connectTimeoutMS=10000`
:timeout_ms	오류가 발생하기 전에 작업이 실행되기를 기다리는 시간(밀리초)입니다. `0` 은 시간 제한이 없음을 의미합니다. 유효하지 않은 시간 제한 값(예: 음수 값 또는 숫자 아닌 값)이 전달되면 클라이언트 생성이 오류로 실패합니다. 데이터 유형: `Integer` 기본값: 없음 클라이언트 예시: `timeout_ms: 5000` 연결 URI 예시: `timeoutMS=5000`

연결 옵션

설명

:connect_timeout

예외가 발생하기 전에 소켓 연결을 설정하기 위해 대기할 시간(초) 입니다. 이 타임아웃은 SRV DNS 기록 해결에도 사용됩니다.

nil 과 0 은 타임아웃이 없음을 의미합니다. 유효하지 않은 타임아웃 값(예: 음수 값 또는 숫자 아닌 값)을 전달하면 클라이언트 생성이 오류로 실패합니다.

데이터 유형: Float
기본값: 10.0
클라이언트 예시: connect_timeout: 10.0
연결 URI 예시: connectTimeoutMS=10000

:timeout_ms

오류가 발생하기 전에 작업이 실행되기를 기다리는 시간(밀리초)입니다.

0 은 시간 제한이 없음을 의미합니다. 유효하지 않은 시간 제한 값(예: 음수 값 또는 숫자 아닌 값)이 전달되면 클라이언트 생성이 오류로 실패합니다.

데이터 유형: Integer
기본값: 없음
클라이언트 예시: timeout_ms: 5000
연결 URI 예시: timeoutMS=5000

서버 선택

연결 옵션	설명
:load_balancing	로드 밸런서에 연결할 준비가 되어 있는지 여부입니다. 데이터 유형: `Boolean` 기본값: `false` 클라이언트 예시: `load_balanced: { true }` 연결 URI 예시: N/A
:server_monitoring_mode	사용할 서버 모니터링 프로토콜. 이 옵션을 `:auto`으로 설정하면 드라이버가 실행되는 환경에 따라 모니터링 모드가 결정됩니다. 드라이버는 Amazon Web Services Lambda와 같은 FaaS(서비스로서의 기능) 환경에서 폴링 모드를 사용하고 다른 환경에서는 스트리밍 모드를 사용합니다. 데이터 유형: `Symbol` 기본값: `:auto` 클라이언트 예시: `server_monitoring_mode: :poll` 연결 URI 예시: `serverMonitoringMode=poll`
:server_selection_timeout	드라이버가 서버 선택이 성공할 때까지 기다리는 최대 시간(초 단위). 데이터 유형: `Integer` 기본값: `30` 클라이언트 예시: `server_selection_timeout: 30` 연결 URI 예시: `serverSelectionTimeoutMS=30000`

서버 선택에 대한 자세한 내용은 서버 선택 가이드를 참조하세요.

인증

연결 옵션	설명
:auth_mech	Ruby 드라이버가 애플리케이션을 인증하는 메카니즘입니다. 데이터 유형: `Symbol` 기본값: `:scram256` 사용자 자격 증명이 제공되지 않은 경우`nil`. 클라이언트 예시: `auth_mech: :scram256` 연결 URI 예시: `authMechanism=SCRAM-SHA-256`
:auth_mech_properties	인증 메커니즘에 특유한 옵션입니다. 이 옵션은 모든 인증 메커니즘에 필요하지 않습니다. 데이터 유형: `Hash` 기본값: GSSAPI 인증 메커니즘을 사용할 때, 기본 속성은 `{service_name: "mongodb"}`입니다. 그렇지 않으면 기본값은 `nil`입니다. 클라이언트 예시: `auth_mech_properties: {aws_session_token: '12345'}` 연결 URI 예시: `authMechanismProperties=AWS_SESSION_TOKEN:12345`
:auth_source	인증할 데이터베이스. 데이터 유형: `String` 기본값: 자격 증명이 제공되면 `admin` 클라이언트 예시: `auth_source: admin` 연결 URI 예시: `authSource=admin`
: user	인증을 위한 사용자 이름입니다. 이 옵션이 연결 URI에 포함되면 백분 인코딩 해야 합니다. 데이터 유형: `String` 기본값: 없음 클라이언트 예시: `user: my+user` 연결 URI 예시: `username=my+user`
:password	인증을 위한 비밀번호입니다. 이 옵션이 연결 URI에 포함되면 백분 인코딩 해야 합니다. 데이터 유형: `String` 기본값: 없음 클라이언트 예시: `password: strong+password` 연결 URI 예시: `password=strong+password`

읽기 및 쓰기 작업

연결 옵션	설명
:replica_set	연결할 복제본 세트의 이름을 지정합니다. 데이터 유형: `String` 기본값: 없음 클라이언트 예시: `replica_set: 'myRS'` 연결 URI 예시: `replicaSet=myRS`
:direct_connection	지정된 호스트에 직접 연결할 지 여부 데이터 유형: `Boolean` 기본값: `false` 클라이언트 예시: `direct_connection: true` 연결 URI 예시: `directConnection=true`
:enable_overload_retargeting	드라이버가 과부하 오류를 반환하는 서버의 우선순위를 낮추는지, 동일한 과부하 서버에서 다시 시도할 가능성을 줄이는지. 데이터 유형: `Boolean` 기본값: `false` 클라이언트 예시: `enable_overload_retargeting: true` 연결 URI 예시: `enableOverloadRetargeting=true`
:max_adoptive_retries	드라이버가 과부하 오류를 발견할 때 시도할 최대 재시도 횟수입니다. 데이터 유형: `Integer` 기본값: `2` 클라이언트 예시: `max_adaptive_retries: 3` 연결 URI 예시: `maxAdaptiveRetries=3`
:read	읽기 설정 (read preference) 옵션. 자세한 내용은 MongoDB Server 매뉴얼의 읽기 설정 (read preference) 을 참조하세요. 데이터 유형: `Hash` 기본값: `{ mode: :primary }` 클라이언트 예시: `read: { mode: :primary }` 연결 URI 예시: `readPreference=primary`
:read_concern	읽기 고려 (read concern) 옵션을 지정합니다. 자세한 내용은 MongoDB Server 매뉴얼의 읽기 고려 (read concern) 를 참조하세요. 데이터 유형: `Hash` 기본값: 없음 클라이언트 예시: `read: { level: :majority }` 연결 URI 예시: `readConcern=majority`
:write_concern	클라이언트의 쓰기 고려 (write concern)를 지정합니다. 자세한 내용은 MongoDB Server 매뉴얼의 쓰기 고려 (write concern) 을 참조하세요. 데이터 유형: `Hash` 기본값: `write_concern: { w: 1 }` 클라이언트 예시: `write_concern: { w: 2 }` 연결 URI 예시: `w=2`
:local_threshold	복제본 세트 노드의 자격에 대한 지연 시간 창(초). 노드의 왕복 핑이 가장 빠른 서버의 왕복 핑 시간에 이 값을 더한 것보다 오래 걸리는 경우 해당 서버는 선택할 수 없습니다. 데이터 유형: `Float` 기본값: `0.015` 클라이언트 예시: `local_threshold: 0.020` 연결 URI 예시: `localThresholdMS=20`

연결 풀

연결 옵션	설명
:max_pool_size	풀이 유지하는 동시 연결의 최대 수입니다. 서버에 대한 사용 중인 연결 수가 지정된 값에 도달하면 해당 서버에 대한 다음 요청은 연결이 사용 가능해질 때까지 대기합니다. 이 옵션을 `0` 으로 설정하면 무제한 연결 풀이 생성됩니다. 데이터 유형: `Integer` 기본값: `100` 클라이언트 예시: `max_pool_size: 100` 연결 URI 예시: `maxPoolSize=100`
:max_connecting	각 풀이 동시에 설정할 수 있는 최대 연결 수입니다. 데이터 유형: `Integer` 기본값: `2` 클라이언트 예시: `max_connecting: 2` 연결 URI 예시: `maxConnecting=2`
:min_pool_size	푸를 유지하는 최소 공시 연결 수. 데이터 유형: `Integer` 기본값: `0` 클라이언트 예시: `min_pool_size: 1` 연결 URI 예시: `minPoolSize=1`
:max_idle_time	풀에서 연결이 유휴 상태로 유지될 수 있는 최대 시간(초)입니다. 데이터 유형: `Integer` 기본값: `0` (제한 없음) 클라이언트 예시: `max_idle_time: 10` 연결 URI 예시: `maxIdleTimeMS=10000`

연결 풀에 대한 자세한 내용은 연결 풀 가이드 참조하세요.

참고

지능형 워크로드 관리(IWM)의 부하 차단

SystemOverloadedError 또는 RetryableError 레이블과 관련된 오류로 인해 애플리케이션에 장애가 발생하거나 애플리케이션 로그에 오류가 나타나는 경우, 클러스터에서 Load Shedding이 활성화되어 있을 수 있으며 드라이버가 이를 지원하는 버전으로 업그레이드되지 않았을 수 있습니다. MongoDB Ruby Driver를 버전 2.24 이상으로 업그레이드하는 것이 좋습니다. 업그레이드 후에도 이러한 오류가 계속 발생하면 Load Shedding 구성 검토와 같은 서버 사이드 변경을 통해 해결하거나, 사용자 지정 오류 처리 또는 클라이언트 사이드 요청 제한 구현과 같은 애플리케이션 사이드 변경을 통해 해결할 수 있습니다. 상황에 따라 애플리케이션 측의 변경이 더 바람직하거나 필요할 수 있습니다.

Load Shedding은 IWM의 기능으로, 지속적인 과부하 상황에서 초과 작업을 거부하여 서버 부하를 관리하는 데 도움이 됩니다. 이 기능은 MongoDB 9.0 이상에서 사용할 수 있습니다.

IWM 또는 과부시 오류 처리에 대한 자세한 내용은 Atlas 문서의 지능형 워크로드 관리 페이지 또는 과부시 오류 페이지를 참조하십시오.

API 문서

Ruby 운전자 의 Mongo::Client 옵션에 대한 자세한 내용은 Mongo::Client에 대한 API 설명서를 참조하세요.

돌아가기

연결 대상 선택

네트워크 트래픽 압축