MongoClient 설정 지정

이 페이지의 내용

개요

MongoClient 설정
클러스터 설정
소켓 설정
연결 풀 설정
서버 설정
TLS/SSL 설정

개요

이 가이드에서는 MongoClient의 동작을 제어하는 다양한 설정에 대해 알아볼 수 있습니다.

다음 섹션에서는 일반적으로 사용되는 설정에 대해 설명합니다.

MongoClient 설정
클러스터 설정
소켓 설정
연결 풀 설정
서버 설정
TLS/SSL 설정

MongoClient 설정

MongoClientSettings 를 생성하고 전달하여 의 동작을 제어할 수 MongoClient 있습니다. 객체를 MongoClient.create() 메서드.

MongoClientSettings 객체를 생성하려면 MongoClientSettings.builder() 메서드와 체인 메서드를 사용하여 설정을 지정하세요. 이들을 연결한 후 build() 메서드를 사용하여 MongoClientSettings 객체를 생성합니다.

다음 표에서는 연결 동작을 수정하기 위해 연결할 수 있는 모든 메서드에 대해 설명합니다.

메서드	설명
`addCommandListener()`	명령 이벤트에 대한 리스너를 추가합니다.
`applicationName()`	`MongoClient`을(를) 사용하여 애플리케이션의 논리적 이름을 설정합니다.
`applyConnectionString()`	지정된 `ConnectionString`의 설정을 빌더에 적용합니다. 이 방법을 생략하면 드라이버는 `localhost`에 연결을 시도합니다.
`applyToClusterSettings()`	`ClusterSettings.Builder` 블록을 적용한 다음 클러스터 설정을 지정합니다.
`applyToConnectionPoolSettings()`	`ConnectionPoolSettings.Builder` 블록을 적용한 다음 연결 풀 설정을 설정합니다.
`applyToServerSettings()`	`ServerSettings.Builder` 블록을 적용한 다음 서버 설정을 설정합니다.
`applyToSocketSettings()`	`SocketSettings.Builder` 블록을 적용한 다음 소켓 설정을 설정합니다.
`applyToSslSettings()`	`SslSettings.Builder` 블록을 적용한 다음 TLS/SSL 설정을 합니다.
`autoEncryptionSettings()`	자동 암호화 설정을 설정합니다.
`codecRegistry()`	코덱 레지스트리를 설정합니다. 코덱 레지스트리를 설정합니다.
`commandListenerList()`	명령 수신기를 설정합니다.
`compressorList()`	서버에 대한 메시지를 압축하는 데 사용할 압축기를 설정합니다.
`credential()`	자격 증명을 설정합니다.
`readConcern()`	읽기 고려를 설정합니다.
`readPreference()`	읽기 설정을 설정합니다.
`retryReads()`	네트워크 오류가 발생하는 경우 드라이버가 읽기를 다시 시도 해야 하는지 여부입니다.
`retryWrites()`	네트워크 오류가 발생하는 경우 드라이버가 쓰기를 다시 시도 해야 하는지 여부입니다.
`serverApi()`	서버에 명령을 보낼 때 사용할 서버 API를 설정합니다.
`streamFactoryFactory()`	`StreamFactory`를 만드는 데 사용할 팩토리를 설정합니다.
`uuidRepresentation()`	UUID 인스턴스를 인코딩하고 서브타입이 3인 BSON 바이너리 값을 디코딩할 때 사용할 UUID 표현을 설정합니다.
`writeConcern()`	쓰기 고려를 설정합니다.

예시

이 예에서는 ConnectionString을 지정하는 방법을 보여줍니다.

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("<your connection string>"))
        .build()
)

팁

각 설정에는 applyConnectionString() 메서드가 있습니다. 설정 내에서는 거의 필요하지 않으므로 앞의 예에 표시된 대로 이 메서드를 사용해야 합니다.

참고

체인 주문

설정의 일부 옵션은 연결 문자열 옵션에 매핑됩니다. 설정 및 연결 문자열에 동일한 옵션을 지정하는 경우, 이를 연결하는 순서에 따라 드라이버에서 사용하는 옵션이 결정됩니다. 드라이버는 마지막으로 읽은 설정을 사용합니다.

예를 들어 이 스니펫은 드라이버가 사용 가능한 소켓에 연결하는 데 걸리는 시간이 다음과 같이 설정되어 있습니다.

다음 항목 이내로 지정된 연결 문자열: 2 SECONDS
소켓 설정은 5 SECONDS 내에서 지정됩니다.

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("mongodb+srv:/<db_username>:<db_password>@<hostname>:<port>?connectTimeoutMS(2000)"))
        .applyToSocketSettings{ builder ->
            builder.connectTimeout(5, TimeUnit.SECONDS)
        }
        .build()
)

드라이버는 소켓 설정 옵션을 마지막으로 읽으므로 드라이버는 시간 초과 전에 5 SECONDS 내에 사용 가능한 소켓에 연결할 것으로 예상합니다.

팁

설정 로그

MongoClient 인스턴스 설정을 기록하려면 org.mongodb.driver.client 로거를 INFO 수준으로 설정합니다.

MongoDB 코틀린(Kotlin) 드라이버를 사용한 로깅에 대해 자세히 알아보려면 로깅 가이드를 참조하세요.

클러스터 설정

applyToClusterSettings() 메서드를 체인으로 연결하여 MongoDB 클러스터와 상호 작용할 때 드라이버의 동작을 수정합니다.

다음 표에서는 설정을 연결하여 드라이버의 동작을 수정할 수 있는 모든 방법을 설명합니다.

메서드

설명

addClusterListener()

클러스터 관련 이벤트에 대한 리스너를 추가합니다.

applyConnectionString()

ConnectionString 객체의 설정을 사용합니다.

applySettings()

ClusterSettings 객체에 지정된 클러스터 설정을 사용합니다.

hosts()

Mongo 서버의 지정된 모든 위치를 설정합니다.

localThreshold()

서버 선택 대상 자격이 박탈되지 않는 선에서 서버가 왕복에 소요할 수 있는 시간을 설정합니다.

mode()

MongoDB Server에 연결하는 방법을 설정합니다.

requiredClusterType()

클러스터에 필요한 클러스터 유형을 설정합니다.

requiredReplicaSetName()

클러스터에 필요한 복제본 세트 이름을 설정합니다.

serverSelectionTimeout()

시간 초과 예외가 발생하기 전에 기본 노드를 선택할 수 있는 최대 시간을 설정합니다.

serverSelector()

서버 선택 전에 적용할 서버 선택기를 추가합니다.

srvHost()

MongoDB 호스트를 찾기 위해 SRV DNS 레코드를 조회할 때 사용할 호스트 이름을 설정합니다.

srvHost 설정 시 드라이버는 호스트와 관련된 모든 관련 TXT 기록을 처리하지 않습니다.

TXT 레코드 처리를 활성화하려면 applyConnectionString() 메서드를 사용하여 연결 문자열에 SRV 호스트를 지정해야 합니다.

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("mongodb+srv://host1.acme.com"))
        .build()
)

srvMaxHosts()

Sets the maximum number of hosts the driver can connect to when using
the DNS seedlist (SRV) connection protocol, identified by the
mongodb+srv connection string prefix.

Throws an exception if you are not using the SRV connection protocol.

예시

이 예에서는 드라이버가 속한 MongoDB 클러스터의 유형에 관계없이 드라이버가 서버에 직접 연결되도록 지정합니다.

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyToClusterSettings{ builder ->
            builder.mode(ClusterConnectionMode.SINGLE)
        }
        .build()
)

팁

이는 연결 URI에 지정할 수 있는 directConnection 매개변수와 유사합니다. 자세한 내용은 연결 옵션을 참조하세요.

소켓 설정

applyToSocketSettings() 메서드를 사용하여 MongoDB 서버에 연결하고 통신할 때 드라이버의 동작을 수정합니다.

다음 표에서는 설정을 연결하여 드라이버의 동작을 수정할 수 있는 모든 방법을 설명합니다.

메서드	설명
`applyConnectionString()`	`ConnectionString` 객체의 설정을 사용합니다.
`applySettings()`	`SocketSettings` 객체에 지정된 소켓 설정을 사용합니다.
`applyToProxySettings()`	`ProxySettings.Builder` 블록을 적용한 다음 `proxySettings` 필드를 설정합니다.
`connectTimeout()`	시간 초과 예외가 발생하기 전에 사용 가능한 소켓에 연결하는 최대 시간을 설정합니다.
`readTimeout()`	시간 초과 예외가 발생하기 전에 사용 가능한 소켓에 읽는 최대 시간을 설정합니다.
`receiveBufferSize()`	수신 시 소켓의 버퍼 크기를 설정합니다.
`sendBufferSize()`	전송 시 소켓의 버퍼 크기를 설정합니다.

예시

이 예시에서는 MongoDB 소켓에서 다음과 같은 드라이버 동작을 지정합니다:

내부에서 사용 가능한 소켓에 연결하려면 다음을 수행합니다. 10 SECONDS
다음 항목 내 사용 가능한 소켓에서 읽기: 15 SECONDS

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("<your connection string>"))
        .applyToSocketSettings{ builder ->
            builder
                .connectTimeout(10, TimeUnit.SECONDS)
                .readTimeout(15, TimeUnit.SECONDS)
        }
        .build()
)

연결 풀 설정

applyToConnectionPoolSettings() 메서드를 연쇄하여 드라이버가 연결 풀을 관리하는 방식을 수정합니다.

다음 표에서는 설정을 연결하여 드라이버의 동작을 수정할 수 있는 모든 방법을 설명합니다.

메서드	설명
`addConnectionPoolListener()`	연결 풀 관련 이벤트에 대한 리스너를 추가합니다.
`applyConnectionString()`	`ConnectionString` 객체의 설정을 사용합니다.
`applySettings()`	`ConnectionPoolSettings` 객체에 지정된 연결 풀 설정을 사용합니다.
`maintenanceFrequency()`	유지 관리 작업 실행 빈도를 설정합니다.
`maintenanceInitialDelay()`	첫 번째 유지 관리 작업을 실행하기 전에 대기할 시간을 설정합니다.
`maxConnectionIdleTime()`	연결이 닫히기 전에 유휴 상태를 지속할 수 있는 최대 시간을 설정합니다.
`maxConnectionLifeTime()`	풀링된 연결이 종료되기 전에 연결이 유지될 수 있는 최대 시간을 설정합니다.
`maxWaitTime()`	사용 가능한 연결을 기다리는 최대 시간을 설정합니다.
`maxSize()`	연결 풀과 연결된 최대 연결 수를 설정합니다.
`minSize()`	연결 풀과 연결된 최소 연결 수를 설정합니다.

참고

이 maxSize 및 minSize 설정은 드라이버를 연결하는 클러스터의 각 서버에 적용됩니다.

예를 들어 3개의 mongos 서버가 있는 클러스터에 드라이버를 연결한다고 가정합니다. 이는 각 mongos 서버에 대해 최대 maxSize 연결과 최소 minSize 연결이 있을 수 있음을 의미합니다.

예시

이 예시에서는 Connection 유형 풀에서 다음 드라이버 동작을 지정합니다.

사용 가능한 연결을 위해 스레드가 최대 10 SECONDS 대기
200을(를) 생략하거나 {2}에서{1}을(를) 거짓으로 설정하면 드라이버가 별도의 내부 {3}을(를) 생성합니다.

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("<your connection string>"))
        .applyToConnectionPoolSettings{ builder ->
            builder
                .maxWaitTime(10, TimeUnit.SECONDS)
                .maxSize(200)
        }
        .build()
)

서버 설정

applyToServerSettings() 메서드를 사용하여 각 MongoDB 서버를 모니터링할 때 드라이버의 동작을 수정합니다.

다음 표에서는 설정을 연결하여 드라이버의 동작을 수정할 수 있는 모든 방법을 설명합니다.

메서드	설명
`addServerListener()`	서버 관련 이벤트에 대한 리스너를 추가합니다.
`addServerMonitorListener()`	서버 모니터 관련 이벤트에 대한 수신자(listener)를 추가합니다.
`applyConnectionString()`	`ConnectionString` 객체의 설정을 사용합니다.
`applySettings()`	`ServerSettings` 객체에 지정된 서버 설정을 사용합니다.
`heartbeatFrequency()`	cluster 모니터가 서버에 연결을 시도하는 간격을 설정합니다.
`minHeartbeatFrequency()`	서버 모니터링 확인의 최소 간격을 설정합니다.
`serverMonitoringMode()`	드라이버가 사용하는 서버 모니터링 프로토콜을 지정합니다.

예시

이 예제에서는 MongoDB Server에서 다음과 같은 드라이버 동작을 지정합니다.

서버 모니터링 확인의 최소 간격은 다음과 같아야 합니다. 700 MILLISECONDS
cluster 모니터는 서버마다 연결을 시도합니다. 15 SECONDS

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("<your connection string>"))
        .applyToServerSettings{ builder ->
            builder
                .minHeartbeatFrequency(700, TimeUnit.MILLISECONDS)
                .heartbeatFrequency(15, TimeUnit.SECONDS)
        }
        .build()
)

TLS/SSL 설정

애플리케이션과 MongoDB 간의 연결을 보호하기 위해 TLS/SSL을 사용할 때 드라이버의 동작을 수정하려면 applyToSslSettings() 메서드를 체인으로 연결합니다.

다음 표에서는 설정을 연결하여 드라이버의 동작을 수정할 수 있는 모든 방법을 설명합니다.

메서드	설명
`applyConnectionString()`	`ConnectionString` 객체의 설정을 사용합니다.
`applySettings()`	`SslSettings` 객체에 지정된 TLS/SSL 설정을 사용합니다.
`context()`	TLS/SSL을 활성화할 때 사용할 `SSLContext`를 설정합니다.
`enabled()`	TLS/SSL 활성화 여부. (Atlas 클러스터의 경우 이 기능을 활성화해야 합니다.)
`invalidHostNameAllowed()`	서버의 호스트 이름과 TLS 인증서에 지정된 호스트 이름 간의 불일치 허용 여부.

예시

이 예시에서는 드라이버가 MongoDB에 연결 시 TLS/SSL을 활성화하도록 지정합니다:

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("<your connection string>"))
        .applyToSslSettings{ builder ->
            builder.enabled(true)
        }
        .build()
)

돌아가기

연결 옵션

네트워크 압축