MongoClient 만들기

이 페이지의 내용

개요

연결 URI
몽고클라이언트
동시 실행
멀티스레딩
다중 포크
멀티프로세싱
유형 힌트
문제 해결
MongoClient 구성 오류 실패
프로세스 포크로 인해 교착 상태 발생
API 문서

개요

MongoDB deployment에 연결하려면 다음 두 가지가 필요합니다.

string연결할 PyMongo MongoDB deployment를 에 알려주는 연결 이라고도 하는 연결 URI 입니다.
MongoDB deployment에 대한 연결을 생성하고 해당 배포에서 작업을 수행할 수 있게 해 주는 MongoClient 객체입니다.

이러한 구성 요소 중 하나를 사용하여 MongoDB에 연결된 동안 PyMongo가 동작하는 방식을 사용자 지정할 수도 있습니다.

이 가이드에서는 연결 string 을 만들고 MongoClient 객체를 사용하여 MongoDB 에 연결하는 방법을 보여 줍니다.

연결 URI

표준 연결 string 에는 다음 구성 요소가 포함됩니다.

구성 요소	설명
`mongodb://`	필수 사항입니다. 표준 연결 형식의 문자열로 식별하는 접두사입니다.
`username:password`	선택 사항. 인증 자격 증명. 이를 포함하면 클라이언트 는 `authSource` 에 지정된 데이터베이스 에 대해 사용자를 인증합니다. `authSource` 연결 옵션에 대한 자세한 내용은 인증 메커니즘을 참조하세요.
`host[:port]`	필수입니다. MongoDB가 실행 중인 호스트 및 선택적 포트 번호입니다. 포트 번호를 포함하지 않으면 드라이버는 기본 포트인 `27017` 을 사용합니다.
`/defaultauthdb`	선택 사항. 연결 string 에 `username:password@` 인증 자격 증명이 포함되어 있지만 `authSource` 옵션이 없는 경우에 사용할 인증 데이터베이스입니다. 이 구성 요소를 포함하지 않으면 클라이언트는 `admin` 데이터베이스에 대해 사용자를 인증합니다.
`?<options>`	선택 사항. 연결별 옵션을 `<name>=<value>` 쌍으로 지정하는 쿼리 string 입니다. 이러한 옵션에 대한 전체 설명은 연결 옵션 지정 을 참조하세요.

연결 생성에 대한 자세한 string 내용은 MongoDB Server 설명서에서 연결 문자열 을 참조하세요.

몽고클라이언트

MongoDB 에 대한 연결을 생성하려면 연결 URI를 string 로 MongoClient 생성자에 전달합니다. 다음 예제에서 드라이버는 샘플 연결 URI를 사용하여 localhost 의 포트 27017 에 있는 MongoDB 인스턴스에 연결합니다.

from pymongo import MongoClient
uri = "mongodb://localhost:27017/"
client = MongoClient(uri)

다음 표에서는 MongoClient() 생성자가 허용하는 위치 매개변수에 대해 설명합니다. 모든 매개변수는 선택 사항입니다.

Parameter

설명

host

MongoDB deployment 의 호스트 이름, IP 주소 또는 Unix 도메인 소켓 경로입니다. 애플리케이션 이 복제본 세트 또는 샤딩된 클러스터 에 연결되는 경우 Python 목록에 여러 호스트 이름 또는 IP 주소를 지정할 수 있습니다.

리터럴 IPv6 주소 전달하는 경우 주소 대괄호([ ])로 묶어야 합니다. 예시 를 들어 [::1] 값을 전달하여 로컬 호스트에 연결합니다.

PyMongo 멀티홈 및 라운드 로빈 DNS 주소를 지원 하지 않습니다.

데이터 유형: Union[str, Sequence[str]] | 기본값: "localhost"

port

MongoDB Server 실행 포트 번호입니다.

이 매개변수를 사용하는 대신 host 인수에 포트 번호를 포함할 수 있습니다.

데이터 유형: int | 기본값: 27017

document_class

클라이언트 쿼리에서 반환된 BSON 문서를 디코딩하는 데 사용하는 기본값 클래스입니다. 이 매개변수는 다음 유형을 허용합니다.

bson.raw_bson.RawBSONDocument. 클래스에 대해 자세히 RawBSONDocument 학습 원시 BSON 데이터로 작업을 참조하세요.
collections.abc.Mapping 유형의 하위 클래스(예: OrderedDict)입니다. 유형 검사 규칙의 엄격성에 따라 다음 예시 와 같이 키와 값의 유형을 지정해야 할 수도 있습니다.
```
client = MongoClient(document_class=OrderedDict[str, int])
```
TypedDict 유형의 하위 클래스입니다. 이 매개변수에 TypedDict 하위 클래스를 전달하려면 다음 예시 와 같이 MongoClient 객체 에 대한 유형 힌트에 클래스를 포함해야 합니다.
```
client: MongoClient[MyTypedDict] = MongoClient()
```
TypedDict typing 3클래스는 모듈에 있으며,8 이는 Python. 이상에서만 사용할 TypedDict 수 있습니다. 이전 버전의 Python 에서 클래스를 사용하려면 타이핑_확장 패키지 설치합니다.

데이터 유형: Type[_DocumentType] 기본값입니다: dict

tz_aware

이 매개변수가 True이면 클라이언트 datetime 값을 인식하는 값으로 처리합니다. 그렇지 않으면 순진한 것으로 취급됩니다.

인식 및 순진한 datetime 값에 대한 자세한 내용은 Python 문서에서 날짜/시간을 참조하세요.

데이터 유형: bool

connect

이 매개 변수가 True인 경우, 클라이언트 MongoDB를 생성한 직후 배경 에서 MongoDB 에 연결하기 시작합니다. 이 매개 변수가 False인 경우 클라이언트 첫 번째 데이터베이스 작업을 수행할 때 MongoDB 에 연결합니다.

애플리케이션 FaaS(서비스로서의 기능) 환경에서 실행 중인 경우 기본값 은 False 입니다. 그렇지 않은 경우 기본값 은 True 입니다.

데이터 유형: bool

type_registry

사용자 지정 유형의 인코딩 및 디코딩을 활성화 클래스의 인스턴스 . 사용자 지정 유형 인코딩 및 디코딩에 대한 TypeRegistry 자세한 내용은 사용자 지정 유형을 참조하세요.

데이터 유형: TypeRegistry

키워드 인수를 MongoClient() 생성자에 전달하여 선택적 매개변수를 지정할 수도 있습니다. 키워드 인수의 전체 목록은 API 문서에서 MongoClient 클래스를 참조하세요.

동시 실행

다음 섹션에서는 PyMongo의 동시 실행 메커니즘 지원 에 대해 설명합니다.

멀티스레딩

PyMongo 는 스레드로부터 안전하며 스레드 애플리케이션을 위한 내장 연결 풀링 제공합니다. 각 MongoClient 객체 데이터베이스 에 대한 연결 풀을 나타내기 때문에 대부분의 애플리케이션은 여러 요청에 걸쳐 MongoClient의 단일 인스턴스 만 필요로 합니다.

다중 포크

PyMongo fork() 메서드 호출을 지원하여 새 프로세스 생성합니다. 그러나 프로세스 포크하는 경우 하위 프로세스 에 새 MongoClient 인스턴스 생성해야 합니다.

중요

MongoClient를 자식 프로세스에 전달하지 않기

fork() 메서드를 사용하여 새 프로세스 만드는 경우 상위 프로세스 에서 MongoClient 클래스의 인스턴스 하위 프로세스 로 전달하지 마세요. 이로 인해 하위 프로세스 의 MongoClient 인스턴스 간에 교착 상태가 발생할 가능성이 높습니다. PyMongo 이 교착 상태가 발생할 수 있는 경우 경고를 발행하려고 시도합니다.

포크된 프로세스의 교착 상태에 대한 자세한 내용은 프로세스 포크로 인해 교착 상태가 발생하는 경우를 참조하세요.

멀티프로세싱

PyMongo Python multiprocessing 모듈을 지원합니다. 그러나 Unix 시스템에서는 멀티프로세싱 모듈이 메서드를 사용하여 프로세스를 fork() 생성합니다. 여기에는 다중 포크에 설명된 것과 동일한 위험이 따릅니다.

PyMongo에서 멀티프로세싱을 사용하려면 다음 예제와 유사한 코드를 작성하세요.

# Each process creates its own instance of MongoClient.
def func():
    db = pymongo.MongoClient().mydb
    # Do something with db.
proc = multiprocessing.Process(target=func)
proc.start()

중요

MongoClient 클래스의 인스턴스를 상위 프로세스에서 하위 프로세스로 복사하지 마세요.

유형 힌트

애플리케이션 에서 Python 이상을 사용하는 경우 3.5 PEP 에 484 설명된 대로 코드에 유형 힌트를 추가할 수 있습니다. 유형 힌트는 변수, 매개변수, 함수 반환 값의 데이터 유형과 문서 구조를 나타냅니다. 일부 IDE는 유형 힌트를 사용하여 코드에 유형 오류가 있는지 확인하고 코드 완성을 위한 적절한 옵션을 제안할 수 있습니다.

PyMongo 애플리케이션 에서 유형 힌트를 사용하려면 다음 예시 와 같이 MongoClient 객체 에 유형 주석을 추가해야 합니다.

client: MongoClient = MongoClient()

더 정확한 유형 정보를 얻으려면 유형 주석에 일반 문서 유형 Dict[str, Any] 을(를) 포함할 수 있습니다. 이 데이터 유형 MongoDB 의 모든 문서와 일치합니다. 다음 예시 이 데이터 유형 유형 주석에 포함하는 방법을 보여줍니다.

from typing import Any, Dict
client: MongoClient[Dict[str, Any]] = MongoClient()

작업 중인 모든 문서가 단일 사용자 지정 유형에 해당하는 경우 MongoClient 객체 에 대한 유형 힌트로 사용자 지정 유형을 지정할 수 있습니다. 이렇게 하면 일반 Dict[str, Any] 유형보다 더 정확한 유형 정보를 제공합니다.

다음 예시 Movie 유형을 MongoClient 객체 에 대한 유형 힌트로 지정하는 방법을 보여 줍니다.

from typing import TypedDict
class Movie(TypedDict):
    name: str
    year: int
client: MongoClient[Movie] = MongoClient()

문제 해결

MongoClient 구성 오류 실패

잘못된 키워드 인수 이름을 제공하면 드라이버에서 이 오류가 발생합니다.

지정한 키워드 인수가 존재하고 철자가 올바른지 확인합니다.

프로세스 포크로 인해 교착 상태 발생

MongoClient 인스턴스는 연결된 서버 모니터링과 같은 백그라운드 작업을 실행하기 위해 여러 스레드를 생성합니다. 이러한 스레드는 클래스의 인스턴스로 보호되는 상태를 공유하며, 이 인스턴스는 자체적 threading.Lock 으로 포크 세이프가 아닙니다 . . PyMongo에는 threading.Lock 클래스 또는 뮤텍스를 사용하는 다른 멀티스레드 코드와 동일한 제한이 적용됩니다.

이러한 제한 사항 중 하나는 fork() 메서드를 호출한 후 잠금이 사용할 수 없게 된다는 것입니다. fork() 이 실행되면 드라이버는 상위 프로세스의 모든 잠금을 상위 프로세스와 동일한 상태로 하위 프로세스에 복사합니다. 상위 프로세스에 잠겨 있으면 하위 프로세스에도 잠깁니다. fork() 가 만든 하위 프로세스에는 스레드가 하나만 있으므로 상위 프로세스의 다른 스레드가 만든 잠금은 하위 프로세스에서 해제되지 않습니다. 다음에 자식 프로세스가 이러한 잠금 중 하나를 얻으려고 시도하면 교착 상태가 발생합니다.

PyMongo 버전 4.3 부터 os.fork() 메서드를 호출한 후 드라이버는 os.register_at_fork() 메서드를 사용하여 하위 프로세스에서 잠금 및 기타 공유 상태를 재설정합니다. 이렇게 하면 교착 상태가 발생할 가능성이 줄어들지만, PyMongo는 OpenSSL 을 포함한 멀티스레드 애플리케이션에서 포크3 세이프가 아닌 라이브러리를 사용합니다. 및 getaddrinfo( ). 따라서 여전히 교착 상태가 발생할 수 있습니다.

fork(2) 에 대한 Linux 매뉴얼 페이지 또한 다음과 같은 제한 사항을 적용합니다.

fork() 멀티스레드 프로그램에서 이후에는 자식이 비동기 신호 안전 함수만 안전하게 호출할 수 있습니다(signal-safety(7 참조). )를 호출할 때까지 execve(2)를 호출합니다.

PyMongo는 비동기 신호에 안전 하지 않은 함수를 사용하기 때문에 하위 프로세스에서 실행할 때 교착 상태 또는 충돌이 발생할 수 있습니다.

팁

하위 프로세스의 교착 상태에 대한 예는 PYTHON-3406 을(를) 참조하세요. Jira에서.

이 6721 있는 멀티스레드 컨텍스트에서 Python 잠금으로 인해 발생하는 문제에 대한 자세한 내용은 fork() 문제 를 참조하세요. Python 이슈 트래커에서.

클라이언트 유형 주석

MongoClient 객체 에 대한 유형 주석을 추가하지 않으면 유형 검사기에 다음과 유사한 오류가 표시될 수 있습니다.

from pymongo import MongoClient
client = MongoClient()  # error: Need type annotation for "client"

해결책은 MongoClient 객체 에 client: MongoClient 또는 client: MongoClient[Dict[str, Any]]로 주석을 추가하는 것입니다.

호환되지 않는 유형

유형 힌트로 MongoClient 를 지정했지만 문서, 키 및 값에 대한 데이터 유형을 포함하지 않는 경우 유형 검사기에 다음과 유사한 오류가 표시될 수 있습니다.

error: Dict entry 0 has incompatible type "str": "int";
expected "Mapping[str, Any]": "int"

해결 방법은 MongoClient 객체 에 다음 유형 힌트를 추가하는 것입니다.

``client: MongoClient[Dict[str, Any]]``

API 문서

PyMongo에서 MongoClient 객체를 만드는 방법에 대해 자세히 알아보려면 다음 API 문서를 참조하세요.

몽고클라이언트

돌아가기

연결

연결 대상 선택