/ /

Transacciones

Overview

En esta guía, puedes aprender a usar el driver de Rust para realizar transacciones. Las transacciones permiten realizar una serie de operaciones que cambian datos sólo si la transacción completa está confirmada. Si alguna operación en la transacción no tiene éxito, el driver detiene la transacción y descarta todos los cambios de datos antes de que se hagan visibles. Esta funcionalidad se denomina atomicidad.

En MongoDB, las transacciones se ejecutan dentro de sesiones lógicas. Una sesión es un grupo de operaciones de lectura o escritura relacionadas que deseas ejecutar de manera secuencial. Las sesiones permiten la coherencia causal para un grupo de operaciones y le permiten ejecutar operaciones en una transacción compatible con ACID, que es una transacción que cumple con una expectativa de atomicidad, consistencia, aislamiento y durabilidad. MongoDB garantiza que los datos involucrados en tus operaciones de transacción permanezcan coherentes, incluso si las operaciones encuentran errores inesperados.

Cuando se utiliza el controlador Rust, se puede crear una nueva sesión a partir de una instancia Client de tipo ClientSession. Puedes mejorar el rendimiento de tu aplicación reutilizando el cliente en múltiples sesiones y transacciones, en lugar de instanciar un cliente nuevo cada vez.

Advertencia

Utilice un ClientSession solo en operaciones que se ejecuten en el Client que lo creó. Usar un ClientSession con un Client diferente da como resultado errores de operación.

Métodos

Crea ClientSession utilizando el método start_session() en tu instancia Client. Luego puedes modificar el estado de sesión utilizando los métodos proporcionados por el tipo ClientSession. La siguiente tabla describe estos métodos:

Método	Descripción
`start_transaction()`	Inicia una nueva transacción, configurada de acuerdo con un parámetro `TransactionOptions` opcional, en esta sesión. La sesión debe pasarse a cada operación dentro de la transacción, o la operación se ejecutará fuera de la transacción. Los errores devueltos de las operaciones ejecutadas dentro de la transacción pueden incluir una etiqueta `TRANSIENT_TRANSACTION_ERROR`, lo que indica que toda la transacción se puede finalizar y luego reintentar con la expectativa de que se realice correctamente. Parámetro: `TransactionOptions`
`commit_transaction()`	Confirma la transacción activa de esta sesión. Este método devuelve un error si no hay una transacción activa para la sesión o si la transacción finalizó anteriormente. Este método podría devolver un error que incluya una etiqueta `UNKNOWN_TRANSACTION_COMMIT_RESULT`, lo que indica que se desconoce si la transacción confirmada satisface el nivel de confirmación de escritura (write concern) establecido. Si encuentra este error, es seguro reintentar la confirmación hasta que se satisfaga el nivel de confirmación de escritura (write concern) o el método devuelva un error sin la etiqueta.
`abort_transaction()`	Termina la transacción activa para esta sesión. Este método devuelve un error si no hay una transacción activa para la sesión o si la transacción fue confirmada o finalizada.
`with_transaction()`	Inicia una transacción en esta sesión y ejecuta la función de retorno dada, luego confirma o finaliza la transacción. Cuando utiliza este método para realizar una transacción, el driver gestiona automáticamente cualquier error, por lo que puede optar por omitir el código de gestión de errores. Debido a que la función de retorno devuelve un futuro y se puede ejecutar varias veces, las reglas de préstamo de cierre del lenguaje Rust para los valores capturados pueden ser restrictivas. Por lo tanto, el método `with_transaction()` acepta un parámetro de contexto que se pasa a la función de retorno. Parámetros: contexto `C`, función de retorno `FnMut(&'a mut ClientSession, &'a mut C)`, `TransactionOptions`

Importante

Métodos que se pueden ejecutar en transacciones

Para ejecutar tareas de MongoDB dentro de transacciones, se deben utilizar los métodos con el sufijo _with_session(). Estos métodos aceptan una instancia de ClientSession como parámetro.

Por ejemplo, para borrar un documento, por lo general se puede usar el método delete_one(). Sin embargo, para borrar un documento dentro de una transacción, se debe usar el método delete_one_with_session() y pasar la sesión como parámetro.

Ejemplo

El siguiente código define la función de retorno insert_media() que insertará datos en las colecciones books y films:

async fn insert_media(session: &mut ClientSession) -> Result<(), Error> {
    let books_coll = session
        .client()
        .database("db")
        .collection::<Document>("books");
    let films_coll = session
        .client()
        .database("db")
        .collection::<Document>("films");
    books_coll.insert_one_with_session(
        doc! { 
            "name": "Sula", 
            "author": "Toni Morrison"
        },
        None,
        session
    ).await?;
    films_coll.insert_one_with_session(
        doc! { "name": "Nostalgia", "year": 1983 },
        None,
        session
    ).await?;
    Ok(())
}

El siguiente código completa las siguientes acciones para realizar la transacción:

Crea una sesión desde el cliente utilizando el método start_session().
Utiliza el método with_transaction() para iniciar una transacción y ejecutar la función de retorno insert_media() dentro de la transacción.

let mut session = client.start_session(None).await?;
session
    .with_transaction((), |session, _| insert_media(session).boxed(), None)
    .await?;
println!("Successfully committed transaction!");

Successfully committed transaction!

Si requiere más control sobre sus transacciones, consulte la documentación del API de ClientSession para encontrar un ejemplo que muestre cómo crear y confirmar manualmente una transacción.

Información Adicional

Para **aprender** más sobre los conceptos mencionados en esta **guía**, consulta las siguientes páginas en el manual del **servidor**:

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.

Para obtener más información sobre las operaciones de inserción, consulte la Guía de Inserción de Documentos.

Documentación de la API

Para obtener más información sobre los métodos y tipos mencionados en esta guía, vea la siguiente documentación de la API:

Volver

Indexes

Colecciones de series de tiempo