연결 가이드

이 페이지의 내용

개요

연결 URI
연결 URI의 부분
MongoDB 클라이언트
클라이언트 생성 방법
연결 예시
MongoDB에 연결하는 다른 방법
로컬 기계에서 MongoDB Server에 연결하기
복제본 세트에 연결

개요

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

이 가이드에는 다음 섹션이 포함되어 있습니다.

연결 URI는 연결 URI와 해당 구성 부분을 설명합니다.
MongoDB 클라이언트 가 Client 유형과 연결 string에서 클라이언트 를 만드는 방법을 설명합니다.
연결 예시에서는 Atlas 연결 문자열을 사용하여 MongoDB에 연결하는 방법을 보여주는 예시를 제공합니다.
MongoDB에 연결하는 다른 방법에서는 Atlas에서 호스팅되지 않는 MongoDB 배포에 연결하는 방법에 대해 설명합니다.

연결 URI

연결 문자열이라고도 하는 연결 URI는 드라이버에 MongoDB에 연결하는 방법과 연결된 동안 동작하는 방법을 알려줍니다.

연결 URI의 부분

다음 예시에서는 샘플 연결 URI의 각 부분을 설명합니다.

이 예시에서는 표준 연결 문자열 형식을 지정하는 프로토콜에 mongodb를 사용합니다. 배포의 유연성을 높이고 클라이언트를 재구성하지 않고도 서버를 교대로 변경할 수 있는 기능을 원하는 경우, DNS 시드 목록 연결 형식을 사용할 수도 있습니다.

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

자격 증명 뒤의 연결 문자열 부분은 MongoDB 인스턴스의 호스트 이름이나 IP 주소 및 포트를 지정합니다. 앞의 예시에서는 sample.host를 호스트 이름으로, 27017을 포트로 사용합니다. 이 값을 MongoDB 인스턴스를 가리키도록 바꿉니다.

연결 문자열의 마지막 부분은 연결 및 인증 옵션을 지정합니다. 위의 예에서는 maxPoolSize=20 및 w=majority의 두 가지 연결 옵션을 설정했습니다.

팁

연결 옵션

연결 옵션 설정에 학습 보려면 연결 옵션에 대한 가이드 를 참조하세요.

MongoDB 클라이언트

MongoDB에 연결하려면 Client 인스턴스를 만들어야 합니다. 클라이언트는 연결을 관리하고 데이터베이스 명령을 실행합니다.

팁

클라이언트 재사용

세션과 작업에서 클라이언트를 재사용하여 성능을 향상시킬 수 있습니다. 매번 새 인스턴스를 만드는 대신 동일한 Client 인스턴스를 사용하여 여러 작업을 수행할 수 있습니다. Client 형식은 여러 스레드 또는 비동기 작업에서 동시에 사용하기에 안전합니다.

클라이언트 생성 방법

ClientOptions 객체를 with_options() 생성자에 전달하여 연결 문자열과 기타 클라이언트 옵션을 사용하는 클라이언트를 만들 수 있습니다.

연결 URI를 지정하려면 이를 ClientOptions 의 parse() 메서드에 전달합니다. 다른 옵션을 설정하려면 ClientOptions 구조체의 관련 필드를 설정합니다.

클라이언트 옵션을 지정하지 않으면 연결 문자열을 Client::with_uri_str() 메서드에 전달하여 클라이언트를 만듭니다.

클라이언트 생성에 학습 보려면 클라이언트 및 with_options()에 대한 API 설명서를 참조하세요.

팁

Stable API

새 서버 버전으로 업그레이드할 때 호환성이 손상되는 변경을 방지하기 위해 스테이블 API 버전을 옵션으로 설정할 수 있습니다.

Stable API 기능에 대해 자세히 알아보려면 Stable API 가이드를 참조하세요.

연결 예시

다음 코드는 Atlas 연결 문자열과 Stable API 버전을 사용하는 클라이언트를 만들고, MongoDB에 연결하고, 연결이 성공했는지 확인하는 방법을 보여줍니다. 해당 연결 코드 샘플을 보려면 아래의 Asynchronous API 또는 Synchronous API 탭에서 선택하세요.

팁

비동기 및 동기 런타임에 대해 자세히 알아보려면 비동기 및 동기 API 가이드를 참조하세요.

use mongodb::{ bson::doc, options::{ ClientOptions, ServerApi, ServerApiVersion }, Client };
#[tokio::main]
async fn main() -> mongodb::error::Result<()> {
    // Replace the placeholder with your Atlas connection string
    let uri = "<connection string>";
    let mut client_options = ClientOptions::parse(uri).await?;
    // Set the server_api field of the client_options object to Stable API version 1
    let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
    client_options.server_api = Some(server_api);
    // Create a new client and connect to the server
    let client = Client::with_options(client_options)?;
    // Send a ping to confirm a successful connection
    client.database("admin").run_command(doc! { "ping": 1 }).await?;
    println!("Pinged your deployment. You successfully connected to MongoDB!");
    Ok(())
}

use mongodb::{ bson::doc, options::{ ClientOptions, ServerApi, ServerApiVersion }, sync::Client };
fn main() -> mongodb::error::Result<()> {
    // Replace the placeholder with your Atlas connection string
    let uri = "<connection string>";
    let mut client_options = ClientOptions::parse(uri)?;
    // Set the server_api field of the client_options object to Stable API version 1
    let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
    client_options.server_api = Some(server_api);
    // Create a new client and connect to the server
    let client = Client::with_options(client_options)?;
    // Send a ping to confirm a successful connection
    client.database("admin").run_command(doc! { "ping": 1 }).run()?;
    println!("Pinged your deployment. You successfully connected to MongoDB!");
    Ok(())
}

팁

빠른 시작 가이드에 따라 Atlas 연결 문자열을 검색하세요.

참고

Atlas Serverless에 연결하는 방법에 대한 자세한 내용은 Serverless Instance Limitations 페이지를 참조하여 필요한 최소 드라이버 버전을 확인하세요.

MongoDB에 연결하는 다른 방법

Atlas에서 호스팅되지 않는 단일 MongoDB 서버 인스턴스 또는 복제본 세트에 연결해야 하는 경우, 다음 섹션을 참조하여 연결 방법을 알아보세요.

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

개발 목적으로 로컬 시스템에서 MongoDB Server를 실행해야 하는 경우 다음을 완료해야 합니다.

MongoDB 설치 튜토리얼에 따라 컴퓨터에 MongoDB Server 를 설치합니다. 시스템 및 운영 체제에 적합한 설치 튜토리얼을 선택합니다.
설치를 완료한 후 서버를 시작합니다.

중요

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

MongoDB Server를 성공적으로 시작한 후 다음 단계를 수행하여 로컬 인스턴스에 연결합니다.

앞의 예제 에서 변수에 저장된 연결 string uri 을 string 로컬 인스턴스의 연결 MongoDB 로 바꿉니다.
MongoDB 서버가 로컬로 실행 중인 경우 다음 연결 문자열을 사용하여 MongoDB에 연결할 수 있습니다.
```
mongodb://localhost:<port>
```
이 연결 문자열에서 <port>는 들어오는 연결을 수신하도록 서버를 구성한 포트 번호입니다.
연결 코드를 실행합니다. 코드가 성공적으로 실행되면 콘솔에 다음 출력이 표시됩니다.
```
Pinged your deployment. You successfully connected to MongoDB!
```

팁

다음도 참조하세요.

연결 문자열 및 사용자 지정 형식에 대해 자세히 알아보려면 서버 매뉴얼의 연결 문자열을 참조하세요.

복제본 세트에 연결

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

복제본 세트 배포서버에 연결하려면 각 인스턴스의 호스트 이름과 포트 번호를 쉼표로 구분하고, 연결 문자열의 replicaSet 매개변수 값으로 복제본 세트 이름을 지정하세요.

다음 예시에서 호스트 이름은 host1, host2, host3이고 포트 번호는 모두 27017입니다. 복제본 세트 이름은 myRS입니다. 다음 코드는 이러한 사양의 복제본 세트에 대한 연결 URI를 보여줍니다.

mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myRS

복제본 세트에 연결할 때 드라이버는 기본적으로 다음 작업을 수행합니다.

한 멤버의 주소가 제공되면 모든 복제본 세트 멤버를 검색합니다.
프라이머리 노드에 대한 쓰기 지침과 같은 작업을 적절한 멤버에게 보냅니다. 복제본 세트 프라이머리에 대해 자세히 알아보려면 MongoDB Server 매뉴얼의 복제본 세트 프라이머리를 참조하세요.

팁

복제본 세트에 연결하려면 하나의 호스트만 지정하면 됩니다. 하지만 지정된 호스트를 사용할 수 없을 때 연결을 보장하려면 전체 호스트 목록을 제공해야 합니다.

직접 연결

연결 URI에 지정된 호스트에서 작업을 강제하려면 directConnection 옵션을 지정합니다. 직접 연결은 다음과 같은 동작을 표시합니다.

SRV 문자열은 지원하지 않습니다.
지정된 호스트가 기본 호스트가 아닌 경우 쓰기에 실패합니다.
지정한 호스트가 프라이머리 노드가 아닌 경우 세컨더리 읽기 설정을 지정하도록 요구합니다. 이러한 복제본 세트 노드에 대해 자세히 알아보려면 서버 매뉴얼에서 복제본 세트 세컨더리 노드를 참조하세요.

돌아가기

연결

연결 옵션