创建 MongoClient

在此页面上

Overview
连接 URI
MongoClient
并发执行
多线程
多个分叉
多重处理
类型提示
故障排除
MongoClient 失败 ConfigurationError
分叉进程会导致死锁
API 文档

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)

下表描述了 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` 类型以及 `collections.abc.Mapping` 类型的子类，例如 `bson.son.SON`。如果您指定 `bson.son.SON` 作为文档类，则还必须指定键和值的类型。数据类型： `Type[_DocumentType]`
`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支持Pythonmultiprocessing 模块。但是，在 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 v3.5 或更高版本，则可以在Python代码中添加类型提示。

以下代码示例展示了如何为 MongoClient对象声明类型提示：

client: MongoClient = MongoClient()

在前面的示例中，代码没有指定 MongoClient对象将使用的文档类型。要指定文档类型，请在创建 MongoClient对象时包含 Dict[str, Any] 类型，如以下示例所示：

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

故障排除

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 问题跟踪器中。

API 文档

要了解有关在 PyMongo 中创建MongoClient对象的更多信息，请参阅以下 API 文档：

MongoClient

后退

连接

来年

选择连接目标