/ /

PyMongo

Operaciones CRUD

Docs Home

Librerías de clientes

Python

PyMongo

Operaciones CRUD

Transacciones

Overview

En esta guía, puedes aprender a utilizar el controlador PyMongo para realizar transacciones. Las transacciones le permiten ejecutar una serie de operaciones que no cambian ningún dato hasta que la transacción se haya confirmado. Si alguna operación en la transacción devuelve un error, el controlador cancela la transacción y descarta todos los cambios de datos antes de que se vuelvan visibles.

En MongoDB, las transacciones se ejecutan dentro de sesiones lógicas. Una sesión es un agrupamiento de operaciones de lectura o escritura relacionadas que se pretende ejecutar secuencialmente. Las sesiones permiten ejecutar operaciones en una transacción compatible con ACID, que es una transacción que cumple con los principios de atomicidad, coherencia, aislamiento y durabilidad. MongoDB garantiza que los datos involucrados en tus operaciones de transacción permanezcan coherentes, incluso si las operaciones experimentan errores inesperados.

Cuando uses PyMongo, puedes crear una nueva sesión desde una instancia MongoClient como un tipo ClientSession. Recomendamos que recicles tu MongoClient para varias sesiones y transacciones en lugar de crear un nuevo cliente cada vez.

Advertencia

Utiliza un ClientSession solo con el MongoClient (o el MongoDatabase o MongoCollection asociados) que lo creaste. El uso de un ClientSession con un MongoClient diferente resulta en errores de operación.

Coherencia causal

MongoDB permite la coherencia causal en las sesiones de los clientes. El modelo de coherencia causal garantiza que las operaciones dentro de una sesión se ejecuten en un orden causal. Los clientes observan resultados que son coherentes con las relaciones causales, o las dependencias entre operaciones. Por ejemplo, si realizas una serie de operaciones en las que una operación depende lógicamente del resultado de otra, cualquier lectura posterior reflejará la relación de dependencia.

Nota

Una sesión de cliente permite la consistencia causal incluso si no realiza una transacción.

La siguiente tabla describe las garantías que ofrecen las sesiones coherentes causales:

garantías	Descripción
Leer las escrituras	Las operaciones de lectura reflejan los resultados de las operaciones de escritura anteriores.
Lecturas monotónicas	Las operaciones de lectura no devuelven resultados que reflejen un estado de datos anterior al de una operación de lectura previa.
Escrituras monotónicas	Si una operación de escritura debe preceder a otras operaciones de escritura, el driver ejecuta primero esta operación de escritura. Por ejemplo, si llamas a `insert_one()` para insertar un documento y luego llamas a `update_one()` para modificar el documento insertado, el controlador ejecutará primero la operación de inserción.
Las escrituras siguen a las lecturas	Si una operación de guardar debe seguir a otras operaciones de lectura, el driver ejecuta primero las operaciones de lectura. Por ejemplo, si llamas a `find()` para recuperar un documento y luego llamas a `delete_one()` para borrar el documento recuperado, el driver ejecuta primero la operación de búsqueda.

En una sesión causalmente consistente, MongoDB garantiza la consistencia causal sólo entre las siguientes operaciones:

Operaciones de lectura que tienen un majority nivel de consistencia de lectura
Operaciones de escritura que tienen un nivel de confirmación de escritura majority

Tip

Para aprender más sobre los conceptos mencionados en esta sección, consulta las siguientes entradas del manual del servidor MongoDB:

Datos de muestra

Los ejemplos en esta guía utilizan la colección sample_restaurants.restaurants de los conjuntos de datos de muestra de Atlas. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consultar el tutorial Comenzar con PyMongo.

Métodos

Después de iniciar una sesión usando el método start_session(), puedes gestionar el estado de la sesión usando los siguientes métodos proporcionados por el ClientSession devuelto:

Método	Descripción
`start_transaction()`	Inicia una nueva transacción, configurada con las opciones dadas, en esta sesión. Devuelve un error si ya hay una transacción en curso para la sesión. Para aprender más sobre este método, consulte la página startTransaction() en el manual del servidor. Parámetros: `read_concern`, `write_concern`, `read_preference`, `max_commit_time_ms` Tipo de devolución: `ContextManager`
`abort_transaction()`	Finaliza la transacción activa de esta sesión. Devuelve un error si no hay ninguna transacción activa o si la transacción ya se ha confirmado o finalizado. Para obtener más información sobre este método, consulte la página `abortTransaction()` del manual del servidor.
`commit_transaction()`	Confirma la transacción activa para esta sesión. Devuelve un error si no hay una transacción activa para la sesión o si la transacción terminó. Para obtener más información sobre este método, consulta la página de commitTransaction() en el manual del servidor.
`with_transaction()`	Inicia una transacción en esta sesión y ejecuta `callback` una vez, luego confirma la transacción. En caso de excepción, este método puede reintentar la confirmación o toda la transacción, lo que puede invocar la función de retorno varias veces mediante una sola llamada a `with_transaction()`. Parámetros: `callback`, `read_concern`, `write_concern`, `read_preference`, `max_commit_time_ms` Valor de retorno: El resultado de la función `callback`
`bind()`	Vincula la sesión a todas las operaciones de la base de datos dentro del ámbito de un administrador de contexto. Llame a este método en un objeto `ClientSession` y, a continuación, utilice el resultado como administrador de contexto. Esto elimina el requisito de pasar `session` a cada operación individual. Parámetros: `end_session` (Opcional, por defecto `True`) Tipo de devolución: `_BoundSessionContext`
`end_session()`	Finaliza esta sesión. Si se ha iniciado una transacción, este método la aborta. Devuelve un error si no hay una sesión activa que terminar.

Un ClientSession también tiene métodos para recuperar propiedades de sesión y modificar propiedades de sesión modificables. Para obtener más información sobre estos métodos, consulta la documentación de la API.

Importante

Si llamas a bind(end_session=False), debes llamar explícitamente a end_session() cuando termines de usar la sesión para evitar el filtrado de información. El siguiente código muestra patrones de uso correctos e incorrectos:

# Incorrect: leaks the session because no reference exists to call
# end_session() on once finished with it
with client.start_session().bind(end_session=False):
    ...
# Correct: end_session=True by default, so session ends automatically
with client.start_session().bind():
    ...
# Correct: session variable allows explicit cleanup
with client.start_session() as s, s.bind(end_session=False):
    ...
s.end_session()
# Correct: nested context managers
with client.start_session() as s:
    with s.bind():
        ...

Ejemplo

El siguiente ejemplo muestra cómo puedes crear una sesión, crear una transacción y confirmar una operación de inserción de varios documentos mediante los siguientes pasos:

Crea una sesión desde el cliente utilizando el método start_session(). Asígnalo a todas las operaciones en el bloque llamando al método bind().
Utiliza el método with_transaction() para iniciar una transacción.
Insertar varios documentos. Debido a que la sesión está vinculada, puede omitir el argumento session de cada operación. El método with_transaction() ejecuta la operación de inserción y confirma la transacción. Si cualquier operación causa errores, with_transaction() cancela la transacción. Este método garantiza que la sesión se cierre correctamente cuando el bloque finalice.
Cierra la conexión con el servidor utilizando el método client.close().

Selecciona la pestaña Synchronous o Asynchronous para ver el código correspondiente:

# Establishes a connection to the MongoDB server
client = MongoClient("<connection string>")
# Defines the database and collection
restaurants_db = client["sample_restaurants"]
restaurants_collection = restaurants_db["restaurants"]
# Function performs the transaction
def insert_documents(session):
    restaurants_collection_with_session = restaurants_collection.with_options(
        write_concern=WriteConcern("majority"),
        read_concern=ReadConcern("local")
    )
    
    # Inserts documents within the transaction
    restaurants_collection_with_session.insert_one(
        {"name": "PyMongo Pizza", "cuisine": "Pizza"}, session=session
    )
    restaurants_collection_with_session.insert_one(
        {"name": "PyMongo Burger", "cuisine": "Burger"}, session=session
    )
# Starts a client session
async with client.start_session() as session:
    try:
        # Uses the with_transaction method to start a transaction, execute the callback, and commit (or abort on error).
        session.with_transaction(insert_documents)
        print("Transaction succeeded")
    except (ConnectionFailure, OperationFailure) as e:
        print(f"Transaction failed: {e}")
# Closes the client connection
client.close()

# Establishes a connection to the MongoDB server
client = AsyncMongoClient("<connection string>")
# Defines the database and collection
restaurants_db = client["sample_restaurants"]
restaurants_collection = restaurants_db["restaurants"]
# Function performs the transaction
async def insert_documents(session):
    restaurants_collection_with_session = restaurants_collection.with_options(
        write_concern=WriteConcern("majority"),
        read_concern=ReadConcern("local")
    )
    
    # Inserts documents within the transaction
    await restaurants_collection_with_session.insert_one(
        {"name": "PyMongo Pizza", "cuisine": "Pizza"}, session=session
    )
    await restaurants_collection_with_session.insert_one(
        {"name": "PyMongo Burger", "cuisine": "Burger"}, session=session
    )
# Starts a client session
with client.start_session() as session:
    try:
        # Uses the with_transaction method to start a transaction, execute the callback, and commit (or abort on error).
        await session.with_transaction(insert_documents)
        print("Transaction succeeded")
    except (ConnectionFailure, OperationFailure) as e:
        print(f"Transaction failed: {e}")
# Closes the client connection
await client.close()

Si requieres más control sobre tus transacciones, puedes utilizar el método start_transaction(). Puedes usar este método con los métodos commit_transaction() y abort_transaction() descritos en la sección anterior para gestionar manualmente el ciclo de vida de la transacción.

Nota

Operaciones paralelas no admitidas

PyMongo no es compatible con la ejecución de operaciones en paralelo dentro de una sola transacción.

Si estás utilizando MongoDB Server v8.0 o una versión posterior, puedes realizar operaciones de escritura en varios espacios de nombres dentro de una sola transacción llamando al método bulk_write() en una instancia MongoClient. Para obtener más información, consulta la Guía de operaciones de escritura masiva.

Información Adicional

Para obtener más información sobre los conceptos mencionados en esta guía, consulta las siguientes páginas del manual de MongoDB Server:

Para aprender más sobre ACID compliance, consulte el ¿Cuáles son las propiedades ACID en los sistemas de gestión de bases de datos? artículo en el sitio web de MongoDB.

Documentación de la API

Para aprender más sobre cualquiera de los tipos o métodos discutidos en esta guía, consulta la siguiente documentación de la API:

Volver

Operaciones de escritura masiva

Almacene archivos grandes