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()`	자동 암호화 설정을 설정합니다. `keyVaultClient`을(를) 생략하거나 `AutoEncryptionSettings`에서`bypassAutomaticEncryption`을(를) 거짓으로 설정하면 드라이버가 별도의 내부 `MongoClient`을(를) 생성합니다. 내부 `MongoClient` 구성은 `minPoolSize`을(를) 0으로 설정하고 `AutoEncryptionSettings`을(를) 생략한다는 점에서 상위 `MongoClient` 구성과 다릅니다.
`codecRegistry()`	코덱 레지스트리를 설정합니다.
`commandListenerList()`	명령 수신기를 설정합니다.
`compressorList()`	서버에 대한 메시지를 압축하는 데 사용할 압축기를 설정합니다.
`credential()`	자격 증명을 설정합니다.
`readConcern()`	읽기 고려를 설정합니다.
`readPreference()`	읽기 설정을 설정합니다. 기본값: `primary`
`retryReads()`	네트워크 오류 발생 시 드라이버 가 읽기 재시도 를 수행할지 여부입니다. 기본값: `true`
`retryWrites()`	네트워크 오류 발생 시 드라이버가 쓰기 재시도 를 수행할지 여부입니다. 기본값: `true`
`serverApi()`	서버에 명령을 보낼 때 사용할 서버 API를 설정합니다.
`transportSettings()`	TransportSettings를 설정합니다.
`uuidRepresentation()`	UUID 인스턴스를 인코딩하고 서브타입이 3인 BSON 바이너리 값을 디코딩할 때 사용할 UUID 표현을 설정합니다.
`writeConcern()`	쓰기 고려를 설정합니다. 기본값: `WriteConcern#ACKNOWLEDGED`. 기본값에 대한 자세한 내용은 암시적 기본 쓰기 고려를 참조하세요.

예제

이 예에서는 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://<username>:<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()

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

기본값: 15 milliseconds

mode()

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

requiredClusterType()

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

requiredReplicaSetName()

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

serverSelectionTimeout()

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

기본값: 30 seconds

serverSelector()

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

srvHost()

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

참고

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

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

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

srvMaxHosts()

DNS 시드 목록(SRV) 연결 프로토콜을 사용할 때 드라이버가 연결할 수 있는 최대 호스트 수를 설정합니다. 이때 mongodb+srv 연결 문자열 접두사를 기준으로 프로토콜을 식별합니다.

SRV 연결 프로토콜을 사용하지 않으면 예외가 발생합니다.

예제

이 예에서는 드라이버가 속한 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()`	연결 풀과 연결된 최대 연결 수를 설정합니다. 기본값: `100`
`maxWaitTime()`	사용 가능한 연결을 기다리는 최대 시간을 설정합니다. 기본값: `2 minutes`
`minSize()`	연결 풀과 연결된 최소 연결 수를 설정합니다. 기본값: `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()`	단일 로그 메시지의 최대 문서 길이(문자)를 설정합니다. 기본값: `1000`

예제

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

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

서버 설정

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

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

메서드	설명
`addServerListener()`	서버 관련 이벤트에 대한 리스너를 추가합니다.
`addServerMonitorListener()`	서버 모니터 관련 이벤트에 대한 수신자(listener)를 추가합니다.
`applyConnectionString()`	`ConnectionString` 객체의 설정을 사용합니다.
`applySettings()`	`ServerSettings` 객체에 지정된 서버 설정을 사용합니다.
`heartbeatFrequency()`	cluster 모니터가 서버에 연결을 시도하는 간격을 설정합니다. 기본값: `10 seconds`
`minHeartbeatFrequency()`	서버 모니터링 확인의 최소 간격을 설정합니다. 기본값: `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()`	시간 초과 예외가 발생하기 전에 사용 가능한 소켓에 연결하는 최대 시간을 설정합니다. 기본값: `10 seconds`
`readTimeout()`	시간 초과 예외가 발생하기 전에 사용 가능한 소켓에서 읽을 최대 시간을 설정합니다. 기본값: `0`, 이는 시간 초과 없음을 나타냅니다.
`receiveBufferSize()`	수신 시 소켓의 버퍼 크기를 설정합니다. 기본값: 운영 체제 기본값
`sendBufferSize()`	전송 시 소켓의 버퍼 크기를 설정합니다. 기본값: 운영 체제 기본값

예제

이 예제에서는 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 설정

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

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

메서드	설명
`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());

← 연결 옵션

네트워크 압축 →

MongoClient 설정 지정.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

개요

MongoClient 설정

예제

참고

체인 주문

팁

설정 로그

클러스터 설정

참고

예제

팁

연결 풀 설정

참고

예제

로거 설정

예제

서버 설정

예제

소켓 설정

예제

TLS/SSL 설정

예제

MongoClient 설정 지정