MongoClient 설정 지정

이 페이지의 내용

개요

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

개요

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

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

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

MongoClient 설정

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

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

다음 표에서는 연결 동작을 수정하기 위해 연결할 수 있는 방법을 설명합니다.

메서드	설명
`addCommandListener()`	명령 이벤트에 대한 리스너를 추가합니다.
`applicationName()`	`MongoClient`을(를) 사용하여 애플리케이션의 논리적 이름을 설정합니다.
`applyConnectionString()`	지정된 `ConnectionString`의 설정을 빌더에 적용합니다. 이 방법을 생략하면 드라이버는 `localhost`에 연결을 시도합니다.
`applyToClusterSettings()`	차단 을 적용한 다음 `ClusterSettings.Builder` 클러스터 설정을 설정합니다.
`applyToConnectionPoolSettings()`	차단 을 적용한 다음 `ConnectionPoolSettings.Builder` 연결 풀 설정을 설정합니다.
`applyToLoggerSettings()`	차단 을 적용한 다음 `LoggerSettings.Builder` 로거 설정을 설정합니다.
`applyToServerSettings()`	차단 을 적용한 `ServerSettings.Builder` 다음 서버 설정을 설정합니다.
`applyToSocketSettings()`	차단 을 적용한 `SocketSettings.Builder` 다음 소켓 설정을 설정합니다.
`applyToSslSettings()`	차단 을 적용한 다음 `SslSettings.Builder` TLS/SSL 설정을 설정합니다.
`autoEncryptionSettings()`	Sets the auto-encryption settings. If you omit `keyVaultClient` or set `bypassAutomaticEncryption` to false in your `AutoEncryptionSettings`, the driver creates a separate, internal `MongoClient`. The internal `MongoClient` configuration differs from the parent `MongoClient` by setting the `minPoolSize` to 0 and omitting the `AutoEncryptionSettings`.
`codecRegistry()`	코덱 레지스트리를 설정합니다.
`commandListenerList()`	명령 수신기를 설정합니다.
`compressorList()`	서버에 대한 메시지를 압축하는 데 사용할 압축기를 설정합니다.
`credential()`	자격 증명을 설정합니다.
`readConcern()`	읽기 고려를 설정합니다.
`readPreference()`	Sets the read preference. Default: `primary`
`retryReads()`	Whether the driver performs retry reads if a network error occurs. Default: `true`
`retryWrites()`	Whether the driver performs retry writes if a network error occurs. Default: `true`
`serverApi()`	서버에 명령을 보낼 때 사용할 서버 API를 설정합니다.
`transportSettings()`	TransportSettings를 설정합니다.
`uuidRepresentation()`	UUID 인스턴스를 인코딩하고 서브타입이 3인 BSON 바이너리 값을 디코딩할 때 사용할 UUID 표현을 설정합니다.
`writeConcern()`	Sets the write concern. Default: `WriteConcern#ACKNOWLEDGED`. For more information about the default value, see Implicit Default Write Concern.

예시

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

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

참고

체인 주문

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

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

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

MongoClient mongoClient = MongoClients.create(
   MongoClientSettings.builder().applyConnectionString(new ConnectionString("mongodb+srv://<db_username>:<db_password>@<hostname>:<port>/<auth db>?connectTimeoutMS=2000"))
      .applyToSocketSettings(builder ->
      builder.connectTimeout(5L, SECONDS))
      .build());

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

팁

설정 로그

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

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

클러스터 설정

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

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

메서드

설명

addClusterListener()

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

applyConnectionString()

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

applySettings()

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

hosts()

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

localThreshold()

Sets the amount of time that a server’s round trip can take and still
be eligible for server selection.

Default: 15 milliseconds

mode()

MongoDB 배포서버에 연결하는 방법을 설정합니다.

requiredClusterType()

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

requiredReplicaSetName()

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

serverSelectionTimeout()

Sets the maximum time to select a primary node before throwing a
timeout exception.

Default: 30 seconds

serverSelector()

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

srvHost()

Sets the host name to use to look up an SRV DNS record to find the
MongoDB hosts.

If you want to enable the processing of TXT records associated with the host,
specify the SRV host in the connection string
using the applyConnectionString() method.

For example:

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

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 클러스터의 유형에 관계없이 드라이버가 서버에 직접 연결되도록 지정합니다.

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
    .applyToClusterSettings(builder ->
        builder.mode(ClusterConnectionMode.SINGLE)
    .build());

팁

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

연결 풀 설정

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

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

메서드	설명
`addConnectionPoolListener()`	연결 풀 관련 이벤트에 대한 리스너를 추가합니다.
`applyConnectionString()`	`ConnectionString` 객체의 설정을 사용합니다.
`applySettings()`	`ConnectionPoolSettings` 객체에 지정된 연결 풀 설정을 사용합니다.
`maintenanceFrequency()`	유지 관리 작업 실행 빈도를 설정합니다.
`maintenanceInitialDelay()`	첫 번째 유지 관리 작업을 실행하기 전에 대기할 시간을 설정합니다.
`maxConnectionIdleTime()`	연결이 닫히기 전에 유휴 상태를 지속할 수 있는 최대 시간을 설정합니다.
`maxConnectionLifeTime()`	풀링된 연결이 종료되기 전에 연결이 유지될 수 있는 최대 시간을 설정합니다.
`maxSize()`	Sets the maximum number of connections associated with a connection pool. Default: `100`
`maxWaitTime()`	Sets the maximum time to wait for an available connection. Default: `2 minutes`
`minSize()`	Sets the minimum number of connections associated with a connection pool. Default: `0`

참고

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

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

예시

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

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

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToConnectionPoolSettings(builder ->
        builder.maxWaitTime(10, SECONDS)
        .maxSize(200)
    .build());

로거 설정

applyToLoggerSettings() 메서드를 체인으로 연결하여 드라이버의 로깅 동작을 수정합니다.

다음 표에서는 로깅 동작을 수정하기 위해 설정을 연결할 수 있는 방법을 설명합니다.

메서드	설명
`maxDocumentLength()`	Sets the maximum document length, in characters, of a single log message. Default: `1000`

예시

이 예에서는 단일 로그 메시지의 최대 문자 수가 5000자로 설정되도록 지정합니다.

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToLoggerSettings(builder ->
         builder.maxDocumentLength(5_000))
    .build());

서버 설정

각 MongoDB 배포를 모니터링할 때 드라이버의 동작을 수정하기 위해 applyToServerSettings() 메서드를 체인으로 연결합니다.

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

메서드	설명
`addServerListener()`	서버 관련 이벤트에 대한 리스너를 추가합니다.
`addServerMonitorListener()`	서버 모니터 관련 이벤트에 대한 수신자(listener)를 추가합니다.
`applyConnectionString()`	`ConnectionString` 객체의 설정을 사용합니다.
`applySettings()`	`ServerSettings` 객체에 지정된 서버 설정을 사용합니다.
`heartbeatFrequency()`	Sets the interval for a cluster monitor to attempt reaching a server. Default: `10 seconds`
`minHeartbeatFrequency()`	Sets the minimum interval for server monitoring checks. Default: `500 milliseconds`

예시

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

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

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToServerSettings(builder ->
        builder.minHeartbeatFrequency(700, MILLISECONDS)
        .heartbeatFrequency(15, SECONDS))
    .build());

소켓 설정

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

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

메서드	설명
`applyConnectionString()`	`ConnectionString` 객체의 설정을 사용합니다.
`applySettings()`	`SocketSettings` 객체에 지정된 소켓 설정을 사용합니다.
`connectTimeout()`	Sets the maximum time to connect to an available socket before throwing a timeout exception. Default: `10 seconds`
`readTimeout()`	Sets the maximum time to read from an available socket before throwing a timeout exception. Default: `0`, which indicates no timeout
`receiveBufferSize()`	Sets the socket's buffer size when receiving. Default: The operating system default
`sendBufferSize()`	Sets the socket's buffer size when sending. Default: The operating system default

예시

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

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

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToSocketSettings(builder ->
        builder.connectTimeout(10, SECONDS)
        .readTimeout(15, 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을 활성화하도록 지정합니다:

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToSslSettings(builder ->
        builder.enabled(true))
    .build());

돌아가기

연결 옵션

네트워크 압축