创建 MongoClient

Overview

要连接到 MongoDB 部署，您需要满足两个条件：

连接 URI ，也称为连接string ，它告诉PyMongo要连接到哪个MongoDB部署。
一个MongoClient对象，用于创建与 MongoDB 部署的连接并允许您对其执行操作。

您还可以使用这些组件来自定义 PyMongo 在连接到 MongoDB 时的行为方式。

本指南向您展示如何创建连接string并使用 MongoClient 对象连接到MongoDB 。

连接 URI

标准连接string包括以下组件：

组件	说明
`mongodb://`	必需。将其标识为标准连接格式中字符串的前缀。
`username:password`	可选。身份验证凭证。如果包含这些内容，客户端将根据`authSource`中指定的数据库对用户进行身份验证。有关`authSource`连接选项的更多信息，请参阅身份验证机制。
`host[:port]`	必需。运行 MongoDB 的主机和可选端口号。如果不包含端口号，驱动程序将使用默认端口`27017` 。
`/defaultauthdb`	可选。如果连接string包含 `username:password@` 身份验证档案但不包含 `authSource` 选项，则要使用的身份验证数据库。如果不包含此组件，客户端将根据`admin`数据库对用户进行身份验证。
`?<options>`	可选。一个查询string ，它将特定于连接的选项指定为 `<name>=<value>` 对。有关这些选项的完整说明，请参阅指定连接选项。

有关创建连接string 的更多信息，请参阅 MongoDB Server文档中的连接字符串。

MongoClient

要创建与MongoDB的连接，请将连接 URI 以string形式传递给 MongoClient 构造函数。在以下示例中，驱动程序使用示例连接 URI 连接到localhost的端口27017上的 MongoDB 实例：

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

如果您使用的是异步应用程序，请使用 AsyncMongoClient 类。以下示例展示了如何创建 AsyncMongoClient对象：

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

下表描述了 MongoClient() 构造函数接受的位置参数。所有参数都是可选的。

Parameter

说明

host

MongoDB 部署的主机名、 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 模块中，该模块仅在Python 3.8 及更高版本中可用。要在早期版本的Python中使用 TypedDict 类，请安装typing_extensions包。

数据类型： Type[_DocumentType] 默认： dict

tz_aware

如果此参数为 True，则客户端会将 datetime 值视为感知值。否则，它将被视为幼稚。

有关感知和初始 datetime 值的更多信息，请参阅Python文档中的日期时间。

数据类型： bool

connect

如果此参数为 True，客户端在创建后立即开始在背景连接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对象添加类型注解，如以下示例所示。选择 Synchronous 或 Asynchronous标签页以查看相应的代码：

from pymongo import MongoClient
client: MongoClient = MongoClient()

from pymongo import AsyncMongoClient
client: AsyncMongoClient = AsyncMongoClient()

要获得更准确的类型信息，可以在类型注解中包含通用文档类型 Dict[str, Any]。此数据类型匹配MongoDB中的所有文档。以下示例展示了如何在类型注解中包含此数据类型。选择Synchronous或Asynchronous标签页以查看相应的代码：

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

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

如果您正在使用的所有文档都对应于一个自定义类型，则可以将该自定义类型指定为 MongoClient对象的类型提示。这提供了比通用 Dict[str, Any] 类型更准确的类型信息。

以下示例展示了如何指定 Movie 类型作为 MongoClient对象的类型提示。选择Synchronous或Asynchronous标签页以查看相应的代码：

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

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

故障排除

MongoClient 失败 ConfigurationError

提供无效的关键字参数名称会导致驱动程序引发此错误。

确保指定的关键字参数存在且拼写正确。

分叉进程会导致死锁

MongoClient实例会生成多个线程来运行后台任务，例如监控已连接的服务器。这些线程共享受threading.Lock 类实例保护的状态，而这些实例本身不是分叉安全的。与使用threading.Lock类或任何互斥锁的任何其他多线程代码一样，PyMongo 也受到相同的限制。

这些限制之一是，在调用fork()方法后，锁将变得无用。当fork()执行时，驱动程序会将父进程的所有锁复制到子进程，其状态与在父进程中的状态相同。如果它们在父进程中被锁定，那么它们也会在子进程中被锁定。 fork()创建的子进程只有一个线程，因此父进程中其他线程创建的任何锁都不会在子进程中释放。下次子进程尝试获取其中一个锁时，就会发生死锁。

从 PyMongo 版本4.3开始，在调用os.fork()方法后，驱动程序使用os.register_at_fork()方法重置其锁和子进程中的其他共享状态。虽然这降低了死锁的可能性，但 PyMongo 依赖于在多线程应用程序中不分叉安全的库，包括 OpenSSL 和 getaddrinfo(3 )。因此，仍可能发生死锁。

fork(2 ) 的 Linux 手册页面还施加了以下限制：

fork()在多线程程序中执行之后，子进程只能安全地调用异步信号安全函数（请参阅信号安全 (7 ））直到调用 execve(2 )。

由于 PyMongo 依赖于异步信号不安全的函数，因此在子进程中运行时可能会导致死锁或崩溃。

提示

有关子进程中死锁的示例，请参阅 PYTHON-3406 在 Jira 中。

有关 Python 在多线程上下文中使用fork() 锁所导致问题的详细信息，请参阅 6721问题在 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 文档：

后退

连接

来年

选择连接目标