/ /

/ /

MongoClient の作成

Overview

MongoDB 配置に接続するには、次の 2 つのものが必要です。

接続 URI （ 接続string とも呼ばれます）で、接続するPyMongo MongoDB配置をに指示します。
MongoDB 配置への接続を作成し、それに対して操作を実行できるようにするMongoClientオブジェクト。

また、これらのコンポーネントのいずれかを使用して、MongoDB に接続中の PyMongo の動作をカスタマイズすることもできます。

このガイドでは、接続string を作成し、{0MongoClient オブジェクトを使用して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ドキュメントの「接続文字列」を参照してください。

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。RawBSONDocument クラスの詳細については、「 Raw BSONデータの操作」を参照してください。
collections.abc.Mapping 型のサブクラス（OrderedDict など）。型チェックルールの厳密性によっては、次の例に示すように、キーと値の型を指定する必要がある場合もあります。
```
client = MongoClient(document_class=OrderedDict[str, int])
```
TypedDict 型のサブクラス。このパラメータに TypedDict サブクラスを渡すには、次の例に示すように、MongoClientオブジェクトの型ヒントにもクラスを含める必要があります。
```
client: MongoClient[MyTypedDict] = MongoClient()
```
TypedDictionクラスは typing モジュールにあります。このモジュールはPython 3.8 以降でのみ利用可能です。Pythonの以前のバージョンで TypedDictクラスを使用するには、 mapping_extentionsパッケージをインストールします。

データ型: Type[_DocumentType] デフォルト: dict

tz_aware

このパラメータが True の場合、クライアントはdatetime の値を認識済みとして扱います。それ以外の場合は、ネイティブとして扱われません。

認識済みおよびネイティブのdatetime 値の詳細については、 Pythonドキュメントの datetime を参照してください。

データ型: bool

connect

このパラメータが True の場合、クライアントは作成後すぐにバックグラウンドでMongoDBへの接続を開始します。このパラメータが False の場合、クライアントは最初のデータベース操作を実行するときにMongoDBに接続します。

アプリケーションがFaaS（function-as-a-service）環境で実行中いる場合、デフォルト値は False です。それ以外の場合、デフォルト値は True です。

データ型: bool

type_registry

カスタム型のエンコードとデコードを有効にする TypeRegistryクラスのインスタンス。カスタムタイプのエンコードとデコードの詳細については、カスタムタイプセクションを参照してください。

データ型: TypeRegistry

また、MongoClient() コンストラクターにキーワード引数を渡して、任意のパラメータを指定することもできます。キーワード引数の完全なリストについては、 APIドキュメントの MongoClientクラスを参照してください。

同時実行

次のセクションでは、PyMongo の同時実行メカニズムのサポートについて説明します。

マルチスレッド

PyMongoはスレッドセーフで、スレッドアプリケーション用の組み込み接続プーリングを提供します。各 MongoClientオブジェクトはデータベースへの接続のプールを表すため、ほとんどのアプリケーションでは、複数のリクエスト間でも MongoClient のインスタンスが 1 つだけ必要になります。

複数のフォーク

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クラスのインスタンスを親プロセスから子プロセスにコピーしないでください。

型ヒント

アプリケーションでPython3.5 以降を使用している場合は、 PHP で説明されているように、型のヒント 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] 型よりも正確な型情報が提供されます。

次の例は、MongoClientオブジェクトの型のヒントとして Movie 型を指定する方法を示しています。

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

MongoClient の終了

ガベージコレクション中に、 PyMongo はMongoClientインスタンスによって使用されるアプリケーション側のリソースを自動的にクリーンアップします。ただし、 PyMongo、開いているカーソルやセッションなどのサーバー側のリソースが閉じられることは保証されません。次の例に示すように、使用が完了したときに MongoClientインスタンスで close() メソッドを呼び出すことで、 PyMongo がこれらのリソースを確実に閉じるようにします。

client.close()

次の例に示すように、with ステートメントでクライアントをインスタンス化することもできます。ブロックが終了すると、クライアントは自動的に閉じます。

with MongoClient("mongodb://localhost:27017/") as client:
   db = client.get_database("mydatabase")
    # Perform further client operations here

トラブルシューティング

MongoClient が ConfigurationError に失敗

無効なキーワード引数名を指定すると、ドライバーはこのエラーを発生させます。

指定したキーワード引数が存在し、正しくスペルされていることを確認します。

プロセスをフォークするとデッドロックが発生する

MongoClientインスタンスは、接続されたサーバーの監視などのバックグラウンドタスクを実行するために複数のスレッドを生成します。これらのスレッドは、threading.Lockクラスのインスタンスによって保護されている状態を共有します。これらのスレッドはそれ自体がフォークセーフではありません。PyMongo には、 threading.Lockクラスまたはミューテックスを使用する他のマルチスレッドコードと同じ制限が適用されます。

これらの制限の 1 つは、 fork()メソッドを呼び出した後にロックが使用できなくなることです。 fork()が実行されると、ドライバーは親プロセスのすべてのロックを、親と同じ状態で子プロセスにコピーします。親プロセスでロックされている場合は、子プロセスでもロックされます。 fork()によって作成された子プロセスにはスレッドが 1 つしかないため、親プロセスの他のスレッドによって作成されたロックは、子プロセスでは解放されません。子プロセスが次にこれらのロックのいずれかを取得しようとすると、デッドロックが発生します。

PyMongoバージョン 4.3 以降では、os.fork() メソッドを呼び出すと、ドライバーは os.register_at_fork() メソッドを使用して子プロセス内のロックやその他の共有状態をリセットします。これによりデッドロックの可能性は減りますが、 PyMongo はOpenSSL や getaddrinfo(3) など、マルチスレッドアプリケーションではフォークセーフではないライブラリに依存しています。そのため、デッドロックは引き続き発生する可能性があります。

fork（2）のLinuxマニュアルページでも次の制限が課されています。

fork()マルチスレッドプログラムでの後、子は explain を呼び出すまでに非同期シグナルセーフな関数のみを安全に呼び出すことができます（シグナルセーフ（7 ） 2を参照）。

PyMongo は非同期シグナルセーフでない関数に依存しているため、子プロセスで実行するとデッドロックやクラッシュが発生する可能性があります。

Tip

子プロセスでのデッドロックの例については、JIRA の Python-3406 を参照してください。

fork() を使用したマルチスレッドコンテキストでのPythonロックが発生する問題の詳細については、 Python問題トポロジーの「問題 6721」を参照してください。

クライアントタイプの注釈

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 ドキュメントを参照してください。

MongoClient

戻る

接続

接続ターゲットの選択