/ /

/ /

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.

Al usar PyMongo, puedes crear una nueva sesión de un MongoClient instancia como tipo ClientSession. Recomendamos que reutilices 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, consulta el Comenzar con PyMongo tutorial.

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()`	Starts a new transaction, configured with the given options, on this session. Returns an error if there is already a transaction in progress for the session. To learn more about this method, see the startTransaction() page in the Server manual. Parameters: `read_concern`, `write_concern`, `read_preference`, `max_commit_time_ms` Return Type: `ContextManager`
`abort_transaction()`	Ends the active transaction for this session. Returns an error if there is no active transaction for the session or the transaction has been committed or ended. To learn more about this method, see the abortTransaction() page in the Server manual.
`commit_transaction()`	Commits the active transaction for this session. Returns an error if there is no active transaction for the session or if the transaction was ended. To learn more about this method, see the commitTransaction() page in the Server manual.
`with_transaction()`	Starts a transaction on this session and runs `callback` once, then commits the transaction. In the event of an exception, this method may retry the commit or the entire transaction, which may invoke the callback multiple times by a single call to `with_transaction()`. Parameters: `callback`, `read_concern`, `write_concern`, `read_preference`, `max_commit_time_ms` Return Value: The result of the `callback` function
`bind()`	Binds the session to all database operations within the scope of a context manager. Call this method on a `ClientSession` object, then use the result as a context manager. This removes the requirement to pass `session` to each individual operation. Parameters: `end_session` (Optional, defaults to `True`) Return Type: `_BoundSessionContext`
`end_session()`	Finishes this session. If a transaction has started, this method aborts it. Returns an error if there is no active session to end.

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 el Synchronous o la pestaña 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