MongoClient 만들기

이 페이지의 내용

몽고클라이언트
예시
연결 URI
DNS 서비스 검색
Atlas 연결 예시
MongoDB에 연결하는 다른 방법
로컬 기계에서 MongoDB deployment에 연결하기
복제본 세트에 연결
자주 묻는 질문
Java 드라이버에 두 가지 유형의 MongoClient 가 있는 이유는 무엇인가요?
어떤 유형의 MongoClient 을(를) 사용해야 하나요?
'java.lang.NoClassDefFoundError: com/mongodb/MongoClient' 오류를 방지하려면 어떻게 해야 하나요?
"com.mongodb.MongoSecurityException" 오류를 방지하려면 어떻게 해야 하나요?
'IllegalStateException: state should be: open' 오류를 방지하려면 어떻게 해야 하나요?

이 가이드에서는 Java 드라이버를 사용하여 MongoDB Atlas 배포서버, MongoDB 인스턴스 또는 복제본 세트에 연결하는 방법을 배울 수 있습니다.

Atlas 클러스터에 연결하기 위한 샘플 코드를 보거나 MongoClient 클래스 및 연결 URI에 대해 자세히 알아볼 수 있습니다.

몽고클라이언트

MongoClient 클래스를 사용하여 MongoDB 에 연결하고 통신할 수 있습니다. MongoClientSettings 객체 만들려면 MongoClientSettings.builder() 메서드와 체인 메서드를 사용하여 설정을 지정합니다. 이들을 연결한 후 build() 메서드를 사용하여 MongoClientSettings 객체 만듭니다.

의 동작을 제어하는 데 사용할 수 있는 다양한 설정에 MongoClient 대해 학습 MongoClient 설정 지정 가이드 참조하세요.

예시

이 예에서는 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 는 데이터베이스 에 대한 연결의 스레드 세이프 풀을 나타내므로 대부분의 애플리케이션은 여러 스레드에 걸쳐서도 MongoClient의 단일 인스턴스 만 필요로 합니다. 최대 연결 수와 같은 모든 리소스 사용량 제한은 개별 MongoClient 인스턴스에 적용 .

팁

인스턴스가 더 이상 필요하지 않을 때는 항상 MongoClient.close() 을 호출하여 리소스를 정리하세요.

연결 URI

연결 URI는 드라이버가 MongoDB 배포에 연결하는 데 사용하는 일련의 지침을 제공합니다. 이는 MongoDB에 연결하는 방법과 연결된 동안 작동하는 방법에 대해 드라이버에 지시합니다. 다음 그림에서는 샘플 연결 URI의 각 부분을 설명합니다.

이 예시 에서는 DNS SRV 기록 있는 MongoDB deployment Atlas 에 연결합니다. 자세한 내용은 이 가이드 의 DNS 서비스 검색 섹션을 참조하세요.

참고

배포서버가 MongoDB Atlas에 있는 경우 Atlas 드라이버 연결 가이드를 참조하고 언어 드롭다운에서 Java를 선택하여 연결 문자열을 검색합니다.

DNS SRV 주소가 없는 인스턴스 또는 복제본 세트에 연결하는 경우 프로토콜에 표준 연결 문자열 형식을 지정하는 mongodb를 사용해야 합니다.

암호 기반 인증 메커니즘을 사용하는 경우 프로토콜 다음에는 연결 문자열에 자격 증명이 포함됩니다. user의 값을 사용자 이름으로 바꾸고 pass를 비밀번호로 바꿉니다. 인증 메커니즘에 자격 증명이 필요하지 않은 경우 연결 URI에서 이 부분을 생략합니다.

연결 URI의 다음 부분은 호스트 이름 또는 IP 주소를 지정하고 그 뒤에 MongoDB 인스턴스의 포트를 지정합니다. 이 예에서 sample.host 은 호스트 이름을 나타내고 27017 은 포트 번호입니다. 이 값을 MongoDB 인스턴스의 포인트 정보로 바꿉니다.

연결 URI의 마지막 부분에는 연결 옵션이 매개 변수로 포함되어 있습니다. 이 예시에서는 maxPoolSize=20 및 w=majority라는 두 가지 연결 옵션을 설정하다. 연결 옵션에 대한 자세한 내용을 보려면 이 가이드의 연결 옵션 지정 섹션으로 건너뛰세요.

DNS 서비스 검색

DNS 서비스 검색을 사용하여 연결하려는 서비스의 DNS SRV 기록 조회하려면 연결 문자열 에 SRV 연결 형식을 지정합니다. 이 형식을 지정하면 Java 운전자 자동으로 새 호스트를 다시 검색합니다. 배포서버 클라이언트 구성을 변경하지 않고도 토폴로지 에 호스트를 추가할 수 있습니다.

다음 코드는 SRV 연결 형식을 사용하는 연결 문자열 보여줍니다.

String uri = "mongodb+srv://<hostname>/";

SRV 연결 형식에 대해 자세히 학습 MongoDB Server 매뉴얼의 SRV 연결 형식 항목을 참조하세요.

Atlas 연결 예시

Atlas에서 MongoDB deployment에 연결하려면 클라이언트를 생성합니다. MongoClientSettings 객체를 MongoClients.create() 생성자에 전달하여 연결 문자열과 기타 클라이언트 옵션을 사용하는 클라이언트를 만들 수 있습니다.

MongoClientSettings 0} 객체를 인스턴스화하려면 빌더 메서드를 사용하여 연결 문자열 및 기타 클라이언트 옵션을 지정한 다음 build() 메서드를 호출하세요. 연결 URI를 지정하려면 applyConnectionString() 메서드를 빌더에 연결하세요.

새 MongoDB 서버 버전으로 업그레이드할 때 호환성이 손상되는 변경을 피하려면 Stable API 버전을 클라이언트 옵션으로 설정할 수 있습니다. Stable API 기능에 대해 자세히 알아보려면 Stable API 페이지를 참조하세요.

다음 코드는 Atlas의 MongoDB deployment에 연결할 때 연결 문자열과 Stable API 클라이언트 옵션을 지정하고 연결이 성공했는지 확인하는 방법을 보여줍니다.

package fundamentals;
import com.mongodb.*;
import org.bson.BsonDocument;
import org.bson.BsonInt64;
import org.bson.Document;
import org.bson.conversions.Bson;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoDatabase;
public class MongoClientConnectionExample {
    public static void main(String[] args) {
        // Replace the placeholder with your Atlas connection string
        String uri = "<connection string>";
        // Construct a ServerApi instance using the ServerApi.builder() method
        ServerApi serverApi = ServerApi.builder()
                .version(ServerApiVersion.V1)
                .build();
        MongoClientSettings settings = MongoClientSettings.builder()
                .applyConnectionString(new ConnectionString(uri))
                .serverApi(serverApi)
                .build();
        // Create a new client and connect to the server
        try (MongoClient mongoClient = MongoClients.create(settings)) {
            MongoDatabase database = mongoClient.getDatabase("admin");
            try {
                // Send a ping to confirm a successful connection
                Bson command = new BsonDocument("ping", new BsonInt64(1));
                Document commandResult = database.runCommand(command);
                System.out.println("Pinged your deployment. You successfully connected to MongoDB!");
            } catch (MongoException me) {
                System.err.println(me);
            }
        }
    }
}

MongoDB에 연결하는 다른 방법

Atlas에서 호스팅되지 않는 단일 MongoDB 배포서버 또는 복제본 세트에 연결하는 경우, 다음 섹션에서 연결 방법을 확인하세요.

로컬 기계에서 MongoDB deployment에 연결하기

Atlas 클러스터를 사용하는 대신 개발 목적으로 로컬 기계에서 MongoDB deployment를 실행해야 하는 경우, 다음을 완료해야 합니다:

MongoDB Server의 Community 또는 Enterprise 버전을 다운로드하세요.
MongoDB 서버를 설치하고 구성합니다.
배포를 시작합니다.

중요

악의적인 공격으로부터 항상 MongoDB 배포를 보호하세요. 보안 체크리스트에서 보안 권장 사항 목록을 확인하세요.

MongoDB deployment를 성공적으로 시작한 후에는 드라이버 연결 코드에 연결 문자열을 지정하세요.

MongoDB deployment가 로컬에서 실행되는 경우 연결 문자열을 "mongodb://localhost:<port>" 사용할 수 있습니다. 여기서 <port>는 수신 연결을 수신하도록 구성한 서버의 포트 번호입니다.

다른 호스트 이름 또는 IP 주소를 지정해야 하는 경우 연결 문자열에 대한 서버 매뉴얼 항목을 참조하세요.

배포서버에 연결할 수 있는지 테스트하려면 MongoDB Atlas에 연결 코드 예시에서 연결 문자열을 바꾸고 실행하세요.

복제본 세트에 연결

MongoDB 복제본 세트 배포는 동일한 데이터 세트를 저장하는 연결된 인스턴스 그룹입니다. 이러한 인스턴스 구성은 데이터 중복성과 높은 데이터 가용성을 제공합니다.

복제 세트 배포에 연결하려면 복제 세트 구성원의 호스트 이름 (또는 IP 주소) 과 포트 번호를 지정합니다.

복제본 세트에 있는 호스트의 전체 목록을 제공할 수 없는 경우, 복제본에 있는 호스트의 단일 또는 하위 집합을 지정하고 다음 방법 중 하나를 사용하여 드라이버가 자동 검색을 수행하도록 지시할 수 있습니다:

복제본 세트의 이름을 replicaSet 매개변수의 값으로 지정합니다.
directConnection 매개 변수의 값으로 false 를 지정합니다.
복제본 세트에 둘 이상의 호스트를 지정합니다.

팁

복제본 세트에 호스트의 하위 집합을 지정할 수 있지만, 호스트 중 하나에 연결할 수 없는 경우 드라이버가 연결을 설정할 수 있도록 복제본 세트에 모든 호스트를 포함하세요.

다음 예에서는 ConnectionString 또는 MongoClientSettings 클래스를 사용하여 MongoClient 인스턴스에 여러 호스트를 지정하는 방법을 보여줍니다. 원하는 수업에 해당하는 탭을 선택합니다.

ConnectionString connectionString = new ConnectionString("mongodb://host1:27017,host2:27017,host3:27017");
MongoClient mongoClient = MongoClients.create(connectionString);

ServerAddress seed1 = new ServerAddress("host1", 27017);
ServerAddress seed2 = new ServerAddress("host2", 27017);
ServerAddress seed3 = new ServerAddress("host3", 27017);
MongoClientSettings settings = MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
               builder.hosts(Arrays.asList(seed1, seed2, seed3)))
        .build();
MongoClient mongoClient = MongoClients.create(settings);

자주 묻는 질문

이 섹션에서는 MongoDB 에 연결할 때 발생할 수 있는 질문에 대한 답변을 제공합니다.

Java 드라이버에 두 가지 유형의 `MongoClient` 가 있는 이유는 무엇인가요?

MongoClient 에는 두 가지 유형이 있는데, 이는 신규 사용자를 위해 여러 개의 CRUD 자주 ASAPI를 포함해야 하는 번거로움을 없애기 위해 보다 깔끔한 API 원했기 때문입니다. 우리는 새로운 CRUD API Java 9에 도입된 Java 모듈 지원 과 잘 작동하는 Java 패키지 구조로 제공되도록 하고 싶었습니다.

어떤 유형의 `MongoClient` 을(를) 사용해야 하나요?

새 애플리케이션은 일반적으로 다음 기능을 지원하는 com.mongodb.client.MongoClient 인터페이스를 사용합니다.

MongoClientSettings 및 ConnectionString로 구성합니다. com.mongodb.client.MongoClients 클래스에 정의된 팩토리 메서드를 사용하여 이 인터페이스의 인스턴스를 만들 수 있습니다.
MongoDatabase 및 여기에서 MongoCollection를 사용하여 CRUD API 에 액세스합니다.

다음 기능을 지원하는 레거시 API 에 대한 지원 필요한 경우 com.mongodb.MongoClient 클래스를 사용하세요.

MongoClientOptions 및 MongoClientURI를 사용하여 구성합니다.
DB 및 여기에서 DBCollection를 사용하여 CRUD API 에 액세스합니다. getDB() 메서드를 사용하여 이 API 액세스 할 수 있습니다.

새 API와 레거시 API를 혼합해야 하는 애플리케이션의 경우 com.mongodb.MongoClient 는 다음 기능도 지원합니다.

MongoClientSettings 및 ConnectionString를 사용하여 구성합니다. 유일한 차이점은 팩토리 클래스 대신 생성자를 통해 인스턴스를 생성한다는 것입니다.
MongoDatabase을(를) 사용하여 CRUD API 에 액세스하고 여기에서 MongoCollection을(를) 사용합니다. getDatabase() 메서드를 사용하여 이 API 액세스 할 수 있습니다.

'java.lang.NoClassDefFoundError: com/mongodb/MongoClient' 오류를 방지하려면 어떻게 해야 하나요?

Java 런타임 환경이 런타임에 클래스 파일을 찾을 수 없는 경우 java.lang.NoClassDefFoundError 예외가 발생할 수 있습니다. MongoDB Java 드라이버를 사용하는 애플리케이션 코드를 실행하려고 하는 경우 클래스 경로에 적절한 드라이버 JAR 파일을 포함해야 합니다.

클래스 경로에 Java 드라이버 JAR 파일을 추가한 후 이 오류가 발생하면 환경에서 다음 항목을 확인하세요.

JAR 파일은 클래스 경로로 지정된 위치에 존재합니다.
클래스 경로 구문이 정확합니다.
환경 변수에 클래스 경로를 정의하면 Java 런타임 환경에서 해당 변수를 사용합니다.
종속성 관리자를 사용하는 경우 해결할 수 없는 충돌은 보고하지 않습니다.

팁

이 오류에는 패키지 및 클래스 이름이 포함되어 있으며, 이는 클래스 경로에서 누락되었을 수 있는 JAR 드라이버를 식별하는 데 도움이 될 수 있습니다. 오류가 참조하는 드라이버 JAR을 찾으려면 API 문서에서 각 항목을 확인하세요.

"com.mongodb.MongoSecurityException" 오류를 방지하려면 어떻게 해야 하나요?

MongoDB deployment에 연결할 때 유효하지 않거나 잘못된 형식의 자격 증명을 지정하면 애플리케이션에서 이 예외가 발생할 수 있습니다.

MongoDB deployment에 연결하려고 할 때 이 오류가 발생하면 코드에서 다음 항목을 확인하세요.

연결 URI가 올바른 MongoDB deployment 에 해당합니다. 연결 URI 설정에 대해 자세히 학습 연결 URI를 참조하세요.
지정한 인증 메커니즘 에 대한 자격 증명 올바른지 확인합니다. 자격 증명 지정하는 방법을 학습 인증 메커니즘 가이드 참조하세요.
지정한 인증 데이터베이스의 이름이 정확합니다. MongoDB deployment에 대한 사용자 및 역할을 설정하는 방법을 알아보려면 MongoDB Server 설명서에서 사용자 및 역할 관리 를 참조하세요.

'IllegalStateException: state should be: open' 오류를 방지하려면 어떻게 해야 하나요?

MongoDB에 대한 연결을 종료한 인스턴스 MongoClient 에서 작업을 호출하는 경우 이 예외가 발생할 수 있습니다. MongoClient 에서 close() 메서드가 호출되면 해당 인스턴스에서 추가 작업을 호출하면 이 예외가 발생합니다.

이 예외를 방지하려면 close() 를 호출하는 코드가 MongoClient 인스턴스에서 실행된 후 해당 인스턴스에 대한 작업을 호출하지 않도록 합니다.

팁

경우에 따라 MongoClient 인스턴스를 닫는 코드를 찾기 어려울 수 있습니다. 이 예외의 잠재적 원인을 찾으려면 다음 사례를 검색하세요.

MongoClient 인스턴스의 close() 호출
가 선언된 try-with-resources 문의 범위를 벗어난 인스턴스에 대한 작업 호출 MongoClient MongoClient

애플리케이션에서 MongoClient 을 managed하기 위해 프레임워크(예: 프레임워크)를 사용하는 경우 프레임워크 문서에서 연결 동작 관리에 대한 권장사항을 찾아보세요.

Spring Boot에서 MongoDB에 액세스하는 방법에 대해 자세히 알아보려면 Spring Boot 및 MongoDB를 참조하세요.

돌아가기

연결

연결 옵션 지정