연결 옵션 지정

개요

이 페이지에서는 PHP 라이브러리에서 사용할 수 있는 MongoDB 연결 및 인증 옵션에 대해 설명합니다.

연결 옵션 설정

연결 URI에 옵션을 지정하거나 옵션을 MongoDB\Client 생성자에 전달하여 연결을 구성할 수 있습니다.

연결 URI 사용

연결 URI를 MongoDB\Client 생성자에 전달하는 경우 URI에 연결 옵션을 <name>=<value> 쌍으로 포함할 수 있습니다. 다음 예시 에서는 연결 URI가 tls 옵션을 true 로 설정하고 tlsCertificateKeyFile 옵션을 /path/to/file.pem 로 설정합니다.

// Replace the placeholders with your actual hostname, port, and path to the certificate key file$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/file.pem';
// Create a MongoDB client$client = new MongoDB\Client($uri);

MongoDB\Client 객체 사용

연결 URI에 연결 옵션을 포함하는 대신 MongoDB\Client 생성자에 연결 옵션을 전달할 수 있습니다.

다음 예시 에서는 MongoDB\Client 생성자의 $uriOptions 매개 변수를 사용하여 연결 옵션을 설정하다 하는 방법을 보여 줍니다.

// Replace the placeholders with your actual hostname and port$uri = 'mongodb://<hostname>:<port>/';
// Set the connection options// Replace the placeholder with the actual path to the certificate key file$uriOptions = [    'tls' => true,    'tlsCertificateKeyFile' => '/path/to/file.pem',];
// Create a MongoDB client with the URI and options$client = new Client($uri, $uriOptions);

참고

$uriOptions 매개변수와 연결 URI 모두에 옵션을 지정하면 $uriOptions 의 값이 우선합니다.

연결 URI 옵션

다음 섹션에서는 MongoDB 연결에 설정하다 수 있는 옵션에 대해 설명합니다. 각 연결 옵션은 MongoDB Server 매뉴얼의 해당 항목으로 연결됩니다.

중요

백분율 인코딩

연결 옵션 값에 특수 문자가 포함된 경우 연결 URI에 포함하기 전에 값을 퍼센트 인코딩해야 합니다. rawurlencode() 메서드를 사용하여 RFC 3986에 지정된 URI 구문에 따라 이러한 값을 인코딩할 수 있습니다.

연결 옵션을 $uriOptions 매개변수에 포함할 때는 퍼센트 인코딩하지 마세요.

자세히 알아보려면 다음 리소스를 참조하세요.

복제본 세트 옵션

연결 옵션	설명
directConnection	데이터 유형: `bool` MongoDB\클라이언트 예시: `$uriOptions = ['directConnection' => true];` 연결 URI 예시: `directConnection=true`
복제본 세트	데이터 유형: `string` MongoDB\클라이언트 예시: `$uriOptions = ['replicaSet' => 'replicaSetName'];` 연결 URI 예시: `replicaSet=replicaSetName`

연결 옵션

TLS 옵션

PHP 라이브러리에서 사용할 수 있는 TLS 옵션에 학습 보려면 TLS 페이지를 참조하세요.

타임아웃 옵션

연결 옵션	설명
connectTimeoutMS	데이터 유형: `int` MongoDB\클라이언트 예시: `$uriOptions = ['connectTimeoutMS' => 2000];` 연결 URI 예시: `connectTimeoutMS=2000`
socketTimeoutMS	데이터 유형: `int` MongoDB\클라이언트 예시: `$uriOptions = ['socketTimeoutMS' => 20000];` 연결 URI 예시: `socketTimeoutMS=20000`

압축 옵션

연결 옵션	설명
압축기	데이터 유형: `string` MongoDB\클라이언트 예시: `$uriOptions = ['compressors' => 'snappy,zstd,zlib'];` 연결 URI 예시: `compressors=snappy,zstd,zlib`
zlibCompressionLevel	데이터 유형: `int` MongoDB\클라이언트 예시: `$uriOptions = ['zlibCompressionLevel' => 3];` 연결 URI 예시: `zlibCompressionLevel=3`

쓰기 고려 옵션

연결 옵션	설명
w	데이터 유형: `string` MongoDB\클라이언트 예시: `$uriOptions = ['w' => 'majority'];` 연결 URI 예시: `w=majority`
wTimeoutMS	데이터 유형: `int` MongoDB\클라이언트 예시: `$uriOptions = ['wTimeoutMS' => 10000];` 연결 URI 예시: `wTimeoutMS=10000`
journal	데이터 유형: `bool` MongoDB\클라이언트 예시: `$uriOptions = ['journal' => true];` 연결 URI 예시: `journal=true`

읽기 고려 옵션

연결 옵션	설명
readConcernLevel	데이터 유형: `string` MongoDB\클라이언트 예시: `$uriOptions = ['readConcernLevel' => 'majority'];` 연결 URI 예시: `readConcernLevel=majority`

읽기 기본 설정 옵션

연결 옵션	설명
읽기 설정	데이터 유형: MongoDB\드라이버\ReadPreference MongoDB\클라이언트 예시: `$uriOptions = ['readPreference' => 'secondaryPreferred'];` 연결 URI 예시: `readPreference=secondaryPreferred`
최대 보관 기간	데이터 유형: `int` MongoDB\클라이언트 예시: `$uriOptions = ['maxStalenessSeconds' => 30];` 연결 URI 예시: `maxStalenessSeconds=30`
readPreferenceTags	데이터 유형: `array` MongoDB\클라이언트 예시: `$uriOptions = [ 'readPreferenceTags' => [ ['dc' => 'ny', 'rack' => 'r1'], [], ],];` 연결 URI 예시: `readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=`

인증 옵션

PHP 라이브러리에서 사용할 수 있는 인증 옵션에 학습 보려면 인증 메커니즘을 참조하세요.

서버 선택/검색 옵션

연결 옵션	설명
localThresholdMS	데이터 유형: `int` MongoDB\클라이언트 예시: `$uriOptions = ['localThresholdMS' => 20];` 연결 URI 예시: `localThresholdMS=20`
serverSelectionTimeoutMS	데이터 유형: `int` MongoDB\클라이언트 예시: `$uriOptions = ['serverSelectionTimeoutMS' => 5000];` 연결 URI 예시: `serverSelectionTimeoutMS=5000`
서버 선택 시도	데이터 유형: `bool` MongoDB\클라이언트 예시: `$uriOptions = ['serverSelectionTryOnce' => false];` 연결 URI 예시: `serverSelectionTryOnce=false`
heartbeatFrequencyMS	데이터 유형: `int` MongoDB\클라이언트 예시: `$uriOptions = ['heartbeatFrequencyMS' => 30000];` 연결 URI 예시: `heartbeatFrequencyMS=30000`
socketCheckIntervalMS	데이터 유형: `int` MongoDB\클라이언트 예시: `$uriOptions = ['socketCheckIntervalMS' => 4000];` 연결 URI 예시: `socketCheckIntervalMS=4000`

기타 구성

연결 옵션	설명
앱 이름	데이터 유형: `string` MongoDB\클라이언트 예시: `$uriOptions = ['appName' => 'myApp'];` 연결 URI 예시: `appName=myApp`
retryReads	데이터 유형: `bool` MongoDB\클라이언트 예시: `$uriOptions = ['retryReads' => false];` 연결 URI 예시: `retryReads=false`
retryWrites	데이터 유형: `bool` MongoDB\클라이언트 예시: `$uriOptions = ['retryWrites' => false];` 연결 URI 예시: `retryWrites=false`
loadBalanced	데이터 유형: `bool` MongoDB\클라이언트 예시: `$uriOptions = ['loadBalanced' => true];` 연결 URI 예시: `loadBalanced=true`
srvMaxHosts	데이터 유형: `int` MongoDB\클라이언트 예시: `$uriOptions = ['srvMaxHosts' => 5];` 연결 URI 예시: `srvMaxHosts=5`

참고

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

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

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

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

API 문서

MongoDB\Client 클래스에 대한 자세한 내용은 다음 PHP 라이브러리 API 문서를 참조하세요.

MongoDB\Client

MongoDB\Driver\ReadPreference 클래스에 대한 자세한 내용은 다음 PHP 확장 API 문서를 참조하세요.

MongoDB\Driver\ReadPreference

돌아가기

연결 대상 선택

Stable API