/ /

Migrate to PyMongo Async

Important

The PyMongo Async driver is experimental and should not be used in production environments. Classes, methods, and behaviors described in this guide might change prior to the full release. If you encounter any issues with PyMongo Async, you can learn how to report them on the Issues & Help page.

Overview

The PyMongo Async driver is a unification of PyMongo and the Motor library. In this guide, you can identify the changes you must make to migrate an application from PyMongo or Motor to the PyMongo Async driver.

Migrate From Motor

The PyMongo Async driver functions similarly to the Motor library, but allows for improved latency and throughput due to directly using Python Asyncio instead of delegating work to a thread pool. In most cases, you can directly migrate existing Motor applications to PyMongo Async by using AsyncMongoClient in place of MotorClient, and changing the application's import statements to import from pymongo.

The following example shows the difference in imports to use a client for read and write operations in Motor compared to PyMongo Async:

# Motor client import
from motor.motor_asyncio import AsyncIOMotorClient
# PyMongo Async client import
from pymongo import AsyncMongoClient

To see a list of the asynchronous methods available in the PyMongo Async API, see the Asynchronous Methods section. To learn about the versions of Motor that correspond to PyMongo, see the Compatibility page.

The following section shows the method signature changes that you must implement in your application when migrating from Motor to the PyMongo Async driver.

Method Signature Changes

The following Motor method signatures behave differently in the PyMongo Async driver:

AsyncMongoClient.__init__() does not accept an io_loop parameter.
AsyncCursor.each() does not exist in the PyMongo Async driver.
MotorGridOut.stream_to_handler() does not exist in the PyMongo Async driver.
AsyncCursor.to_list(0) is not valid in the PyMongo Async driver. Use to_list(None) instead.
MongoClient is thread safe and can be used by many threads, however, an AsyncMongoClient is not thread safe and should only be used by a single event loop.

Migrate from PyMongo

The PyMongo Async driver behaves similarly to PyMongo, but all methods that perform network operations are coroutines and must be awaited. To migrate from PyMongo to PyMongo Async, you must update your code in the following ways:

Replace all uses of MongoClient with AsyncMongoClient.
Add the await keyword to all asynchronous method calls.
If you call an asynchronous method inside of a function, mark the function as async.

The following sections describe how to implement the asynchronous API.

Asynchronous Methods

The following tables list the asynchronous methods that are available in the PyMongo Async driver. To call these methods, you must await them and call them inside an async function.

Client Methods

Method

Example

AsyncMongoClient()

from pymongo import AsyncMongoClient
async with AsyncMongoClient(...)

watch()

async with await client.watch(...) as stream:
   ...

server_info()

await client.server_info(...)

list_databases()

await client.list_databases()

list_database_names()

await client.list_database_names()

drop_database()

await client.drop_database(...)

Database Methods

Method

Example

watch()

async with await db.watch(...) as stream:
   ...

create_collection()

await db.create_collection(...)

aggregate()

async with await client.admin.aggregate(...) as cursor:
   ...

command()

await db.command(...)

cursor_command()

await db.cursor_command(...)

list_collections()

await db.list_collections()

list_collection_names()

await db.list_collection_names()

drop_collection()

await db.drop_collection(...)

validate_collection()

await db.validate_collection(...)

dereference()

await db.dereference(...)

Collection Methods

Method

Example

watch()

async with await collection.watch(...) as stream:
   ...

insert_one()

await collection.insert_one(...)

insert_many()

await collection.insert_many(...)

replace_one()

await collection.replace_one(...)

update_one()

await collection.update_one(...)

update_many()

await collection.update_many(...)

drop()

await collection.drop()

delete_one()

await collection.delete_one(...)

delete_many()

await collection.delete_many(...)

find_one()

await collection.find_one(...)

estimated_document_count()

await collection.estimated_document_count()

count_documents()

await collection.count_documents(...)

create_index()

await collection.create_index(...)

create_indexes()

await collection.create_indexes(...)

drop_index()

await collection.drop_index(...)

drop_indexes()

await collection.drop_indexes()

list_indexes()

await collection.list_indexes()

index_information()

await collection.index_information()

list_search_indexes()

await collection.list_search_indexes()

create_search_index()

await collection.create_search_index(...)

create_search_indexes()

await collection.create_search_indexes(...)

drop_search_index()

await collection.drop_search_index(...)

update_search_index()

await collection.update_search_index(...)

options()

await collection.options()

aggregate()

async for doc in await collection.aggregate(...):
   ...

aggregate_raw_batches()

async for batch in await collection.aggregate_raw_batches(...):
   ...

rename()

await collection.rename(...)

distinct()

await collection.distinct(...)

find_one_and_delete()

await collection.find_one_and_delete(...)

find_one_and_replace()

await collection.find_one_and_replace(...)

find_one_and_update()

await collection.find_one_and_update(...)

Additional Information

To learn more about asynchronous Python, see the Python Asyncio documentation.

Back

Upgrade Guides

Previous Versions