/ /

연결 옵션 지정

이 섹션에서는 MongoClientOptions 인스턴스 내에서 설정하다 수 있는 Node.js 운전자 에서 지원하는 MongoDB 연결 및 인증 옵션에 대해 설명합니다.

연결 문자열 에서 직접 연결 옵션을 설정하는 방법에 대한 자세한 내용은 MongoDB Server 매뉴얼에서 연결 문자열을 참조하세요.

이름	허용되는 값	기본값	설명
앱 이름	문자열	`null`	연결 핸드셰이크의 일부로 드라이버가 서버에 전달하는 앱 이름을 클라이언트 메타데이터에 지정합니다. 드라이버는 연결 구축 시 MongoDB에 `appName` 값을 보냅니다. 이 값은 로그 파일, 느린 쿼리 로그 및 프로필 컬렉션에 기록됩니다.
authMechanism	문자열	`null`	서버 연결에 사용할 인증 메커니즘 방법을 지정합니다. 값을 지정하지 않으면 운전자 서버 버전에 따라 `SCRAM-SHA-1` 또는 `SCRAM-SHA-256` 기본값 메커니즘을 사용합니다. 사용 가능한 인증 메커니즘은 인증 메커니즘 섹션을 참조하세요.
authMechanismProperties	쉼표로 구분된 키: 'opt1:val1,opt2:val2'와 같은 값 쌍	`null`	GSSAPI에 대한 호스트 이름 정규화 활성화와 같이 인증을 위해 제공되는 다른 옵션을 지정합니다.
authSource	문자열	`null`	연결이 인증할 데이터베이스를 지정합니다.
autoSelectFamily	부울	`true`	`true`로 설정하다 하면 소켓은 연결이 설정될 때까지 IPv6 및 IPv4 주소에 연결을 시도합니다. 사용 가능한 경우 운전자 첫 번째 IPv6 주소 선택합니다.
autoSelectFamilyAttemptTimeout	non-negative integer	`null`	`autoSelectFamily` 옵션을 사용할 때 다음 주소 시도하기 전에 연결 시도가 완료될 때까지 기다리는 시간을 밀리초 단위로 지정합니다. `10`보다 작은 양의 정수로 설정하다 하면 `10` 값이 대신 사용됩니다.
압축기	'snappy,zlib,zstd'와 같이 쉼표로 구분된 문자열 목록	`null`	서버와 주고받는 유선 프로토콜 메시지에 허용되는 압축 유형을 지정합니다. 자세한 내용은 네트워크 압축을 참조하세요.
connectTimeoutMS	non-negative integer	`30000`	오류가 발생하기 전에 서버 에 단일 TCP 소켓 연결을 설정하기 위해 대기할 시간(밀리초)을 지정합니다. `0` 을 지정하면 애플리케이션 소켓을 설정할 때 무한 소켓 시간 제한을 설정합니다.
directConnection	부울	`false`	연결 URI에 지정된 호스트에 모든 작업을 강제로 디스패치할지 여부를 지정합니다.
enableUtf8Validation	부울	`true`	`true`을 지정하면 연결에 대해 UTF-8 유효성 검사가 활성화됩니다.MongoDB는 유효하지 않은 UTF-8 문자가 포함된 문자열 데이터를 BSON으로 직렬화하려고 시도하면 오류를 발생시킵니다. 이는 문서 키와 문서 값 모두에 적용되며, 이 유효성 검사는 처리 오버헤드를 추가합니다. `false`로 지정하면 연결에 대한 UTF-8 유효성 검사가 비활성화됩니다. 데이터에 유효하지 않은 UTF-8 데이터가 포함되어 있어도 MongoDB는 오류를 발생시키지 않습니다. 유효성 검사를 비활성화 하면 응용 프로그램에서 유효성 검사 처리 오버헤드를 방지할 수 있습니다. 유효성 검사를 비활성화 한 상태에서 데이터를 편집하면 데이터가 손실될 수 있습니다. UTF-8 유효성 검사를 비활성화 하는 것은 데이터를 쿼리하거나 내보내기만을 위한 일시적인 해결책입니다. UTF-8 문자에 대해 자세히 학습 Wikipedia의 UTF-8 를 참조하세요.
heartbeatFrequencyMS	500보다 크거나 이와 동일한 정수	`null`	정기적인 서버 모니터링 확인 사이의 간격(밀리초)을 지정합니다.
loadBalanced	부울	`null`	드라이버가 로드 밸런서에 연결 중인지 여부를 지정합니다.
localThresholdMS	non-negative integer	`15`	적합한 서버를 선택하기 위한 왕복 시간에서 지연 시간 창의 크기(밀리초)를 지정합니다. `0`을 지정하면 대기 시간이 없으므로 사용 가능한 가장 빠른 서버를 사용할 수 있습니다.
maxIdleTimeMS	non-negative integer	`0`	연결이 닫히기 전 유휴 상태가 유지될 수 있는 시간(밀리초)을 지정합니다. `0`을 지정하면 최소값이 없습니다.
maxPoolSize	non-negative integer	`100`	드라이버가 연결 풀에 생성할 수 있는 최대 클라이언트 또는 연결 수를 지정합니다. 이 수에는 사용 중인 연결이 포함됩니다.
maxConnecting	non-negative integer	`2`	드라이버의 연결 풀이 동시에 설정할 수 있는 최대 연결 수를 지정합니다.
최대 보관 기간	-1 또는 90보다 크거나 90과 같은 정수	`null`	세컨더리가 경험할 수 있고 계속해서 서버 선택에 적합한 실제 시간 기준으로 측정된 최대 복제 지연 시간을 나타냅니다. `-1`을 지정하면 최대값이 없습니다.
minPoolSize	non-negative integer	`0`	작업이 발생하지 않는 경우에도 드라이버가 연결 풀에서 생성하고 유지 관리하는 연결 수를 지정합니다. 이 수에는 사용 중인 연결이 포함됩니다.
proxyHost	문자열	`null`	SOCKS5 프록시 IPv4 주소, IPv6 주소 또는 도메인 이름을 지정합니다.
proxyPort	non-negative integer	`null`	SOCKS5 프록시 서버의 TCP 포트 번호를 지정합니다. `proxyHost` 옵션을 설정하면 이 옵션의 기본값은 `1080`(으)로 설정됩니다.
proxyUsername	문자열	`null`	SOCKS5 프록시 서버에 인증할 사용자 이름을 지정합니다. 이 옵션을 길이가 0인 문자열로 설정하면 드라이버는 이를 무시합니다.
proxyPassword	문자열	`null`	SOCKS5 프록시 서버에 대한 인증을 위한 비밀번호를 지정합니다. 이 옵션을 길이가 0인 문자열로 설정하면 드라이버는 이를 무시합니다.
readConcernLevel	문자열	`null`	클라이언트에 대한 기본 읽기 고려를 지정합니다. 자세한 내용은 읽기 고려를 참조하세요.
읽기 설정	문자열	`"primary"`	클라이언트의 기본 읽기 설정(태그 제외)을 지정합니다. 자세한 내용은 읽기 설정을 참조하세요.
readPreferenceTags	쉼표로 구분된 키:값 쌍(예시: "dc:ny,rack:1" and "dc:ny는 여러 번 지정할 수 있으며, 이 키의 각 인스턴스는 별도의 태그 세트입니다.	`null`	클라이언트에 대한 기본 읽기 설정 태그를 지정합니다. 이 옵션은 읽기 설정 모드가 프라이머리가 아닌 경우에만 유효합니다. 드라이버는 URI의 태그 순서를 읽기 설정 순위로 사용합니다.
복제본 세트	문자열	`null`	연결한 복제본 세트의 이름을 지정합니다.
retryReads	부울	`true`	재시도 가능 읽기를 활성화합니다.
retryWrites	부울	`true`	재시도 가능 쓰기를 활성화합니다.
serverMonitoringMode	`auto`, `stream`, `poll`	`auto`	드라이버 모니터가 사용하는 모니터링 모드를 지정합니다. 이 옵션을 `auto`로 설정하면 드라이버가 실행되는 환경에 따라 모니터링 모드가 결정됩니다. 드라이버는 FaaS(서비스로서의 기능) 환경에서 폴링 모드를 사용하고 다른 환경에서는 스트리밍 모드를 사용합니다.
serverSelectionTimeoutMS	non-negative integer	`30000`	오류가 발생하기 전에 서버 선택을 차단하는 제한 시간(밀리초)을 지정합니다.
socketTimeoutMS	non-negative integer	`0`	시간이 초과되기 전에 소켓에서 전송 또는 수신을 시도하는 데 소요되는 시간(밀리초)을 지정합니다. `0` 을 지정하면 애플리케이션 소켓을 설정할 때 무한 소켓 시간 제한을 설정합니다.
srvMaxHosts	non-negative integer	`0`	시드 목록을 처음 채울 때 또는 SRV 폴링 중에 토폴로지에 새 호스트를 추가할 때 무작위로 선택할 SRV 결과의 최대 개수를 지정합니다.
srvServiceName	RFC 6335에 따른 유효한 SRV 서비스 이름	`"mongodb"`	초기 DNS 시드 목록 검색에서 SRV 조회에 사용할 서비스 이름을 지정합니다.
ssl	부울	`false`	`ssl`는 `tls` 옵션의 별칭입니다.
TLS	부울	`false`	서버에 연결할 때 TLS가 필요한지 여부를 지정합니다. `"mongodb+srv"`의 `srvServiceName`을 사용하거나 다른 `tls` 접두사가 붙은 옵션을 지정하면 암시적으로 `tls` 값이 `true`로 설정됩니다.
tlsAllowInvalidCertificates	부울	`false`	서버의 TLS 인증서가 유효하지 않은 경우 드라이버가 오류를 생성하는지 여부를 지정합니다. 테스트 목적으로만 이 옵션을 `true`로 설정합니다.
tlsAllowInvalidHostnames	부울	`false`	서버의 호스트 이름과 TLS 인증서에 지정된 호스트 이름이 일치하지 않을 때 드라이버가 오류를 생성할지 여부를 지정합니다. 테스트 목적으로만 이 옵션을 `true`로 설정합니다.
tlsCAFile	문자열	`null`	TLS 연결을 작성할 때 신뢰할 수 있는 인증 기관의 단일 또는 번들이 있는 파일의 경로를 지정합니다. 이 연결 옵션 설정에 대해 자세히 알아보려면 TLS 가이드의 인증서 파일 경로 제공 섹션을 참조하세요.
tlsCertificateKeyFile	문자열	`null`	클라이언트 인증서 파일 또는 클라이언트 개인 키 파일의 경로를 지정합니다. 둘 다 필요한 경우 파일을 연결해야 합니다. 이 연결 옵션 설정에 대해 자세히 알아보려면 TLS 가이드의 인증서 파일 경로 제공 섹션을 참조하세요.
tlsCertificateKeyFilePassword	문자열	`null`	TLS 연결에 사용할 클라이언트 개인 키를 해독하기 위한 비밀번호를 지정합니다.
tlsInsecure	부울	`false`	유효하지 않은 인증서나 호스트 이름 불일치를 허용하는 등 TLS 제약 조건을 최대한 완화하도록 지정합니다. 테스트 목적으로만 이 옵션을 `true`로 설정합니다.
waitQueueTimeoutMS	non-negative integer	`0`	시간이 초과되기 전에 서버의 연결 풀에서 연결 확인을 시도하는 시간(밀리초)을 지정합니다. `0` 은 시간 초과가 없음을 의미합니다.
zlibCompressionLevel	`-1`에서 `9` 사이의 정수(포괄적)	`-1`	zlib를 사용하여 유선 프로토콜 메시지를 압축할 때 압축 수준을 지정합니다. `-1`은 기본 수준을 나타내고, `0`은 압축이 없음을 나타내고, `1`은 가장 빠른 속도를 나타내고, `9`는 최상의 압축을 나타냅니다. 자세한 내용은 네트워크 압축을 참조하세요.

연결 시간 초과 옵션

설정	설명
connectTimeoutMS	`connectTimeoutMS` 연결 풀 의 개별 연결이 시간이 초과되기 전에 MongoDB Server 에 TCP 연결을 설정하는 데 걸리는 시간(밀리초)을 설정하는 연결 옵션입니다. MongoClient.connect가 MongoDB Server 에 연결하는 데 허용되는 시간을 수정하려면 `serverSelectionTimeoutMS` 옵션을 대신 사용합니다. 기본값: 30000
socketTimeoutMS	`socketTimeoutMS` 드라이버가 비활성 소켓을 닫기 전에 기다리는 시간을 지정합니다. 기본값은 소켓 시간 초과를 하지 않는 것입니다. 이 옵션은 이미 연결된 소켓에만 적용됩니다.
최대 시간 (MS)	maxTimeMS 는 작업이 서버에 도달한 후 완료될 때까지 서버가 대기하는 최대 시간을 지정합니다. 작업이 지정된 시간 제한을 초과하여 실행되면 시간 초과 오류가 반환됩니다. `maxTimeMS` 는 개별 작업이나 커서 에만 전달할 수 있습니다.

MongoClient에 대한 선택적 설정을 지정하려면 다음과 같이 생성자의 options 객체에 사용 가능한 설정을 하나 이상 선언합니다.

const client = new MongoClient(uri, {
  connectTimeoutMS: <integer value>,
  socketTimeoutMS: <integer value>
});

사용 가능한 모든 설정을 보려면 MongoClientOptions API 문서를 참조하세요.

maxTimeMS를 지정하려면 Cursor를 반환하는 작업에 maxTimeMS 메서드를 시간 초과 사양이 있는 옵션으로 전달합니다.

const Cursor = collection.distinct('my-key', { maxTimeMS: 50 });

연결 후 소켓 닫기

예기치 않은 네트워크 동작이 발생하거나 MongoDB 프로세스 오류로 인해 실패하는 경우 운전자 해당 소켓을 올바르게 닫았다는 확인을 받지 못할 수 있습니다.

이러한 경우 드라이버가 소켓을 올바르게 닫는지 확인하려면 socketTimeoutMS 옵션을 설정합니다. MongoDB 프로세스가 시간 초과되면 드라이버는 소켓을 닫습니다. 애플리케이션이 실행하는 가장 느린 작업의 예상 지속 시간보다 2~3배 긴 socketTimeoutMS 값을 선택하는 것이 좋습니다.

장기 실행 작업으로 인한 서버 속도 저하 방지

시간 초과 값을 지정하여 장기 실행 작업으로 인해 서버 속도가 느려지는 것을 방지할 수 있습니다. 특정 작업에 대한 시간 초과를 설정하기 위해 Cursor를 반환하는 작업에 maxTimeMS() 메서드를 연결할 수 있습니다.

다음 예에서는 Cursor를 반환하는 작업에 maxTimeMS() 메서드를 연결하는 방법을 보여줍니다.

// Execute a find command
await collection
  .find({ $where: "sleep(100) || true" })
  .maxTimeMS(50);

keepAlive 연결 옵션

keepAlive 연결 옵션은 TCP 소켓에서 TCP(전송 제어 프로토콜) 킵얼라이브 를 활성화 할지 여부를 지정합니다. 킵얼라이브를 활성화 운전자 MongoDB deployment 에 주기적으로 핑을 전송하여 연결이 활성 상태인지 확인합니다. 이 기능은 운영 체제가 SO_KEEPALIVE 소켓 옵션을 지원하는 경우에만 작동합니다.

keepAliveInitialDelay 옵션은 킵얼라이브를 시작하기 전에 드라이버가 대기하는 시간을 밀리초 단위로 지정합니다.

5.3 드라이버 버전 릴리스에서는 이러한 옵션이 더 이상 사용되지 않습니다. 드라이버 버전 6.0부터 keepAlive 옵션은 영구적으로 true로 설정되고 keepAliveInitialDelay는 300000밀리초(300초)입니다.

경고

방화벽이 킵얼라이브 메시지를 무시하거나 제거하는 경우 제거된 연결을 식별하지 못할 수도 있습니다.

추가 정보

MongoClientOptions 인스턴스 내에서 설정하다 수 있는 연결 옵션에 대해 자세히 학습하려면 API 설명서에서 MongoClientOptions 를 참조하세요.

돌아가기

연결 가이드

네트워크 트래픽 압축