연결 옵션 지정

이 섹션에서는 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를 참조하세요.

돌아가기

MongoClient 만들기

네트워크 트래픽 압축