/ /

Driver Rust

Operaciones CRUD

Docs Home

Librerías de clientes

Rust

Driver Rust

Operaciones CRUD

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 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. Puede establecer opciones de transacción encadenando los métodos del desarrollador de opciones `TransactionOptions` a `start_transaction()`. 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.
`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.
`and_run()`	Ejecuta la función de retorno dada y, a continuación, confirma o finaliza la transacción. El driver reintenta las función de retorno y las confirmaciones que generan un error con una etiqueta `TRANSIENT_TRANSACTION_ERROR`. Si generan cualquier otro error, el driver finaliza la transacción y devuelve el error a la persona que llama. 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. Dado 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 `and_run()` 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)`

Importante

Métodos que se pueden ejecutar en transacciones

Para ejecutar operaciones de MongoDB dentro de transacciones, debes encadenar el método session() a la operación. Este método acepta 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, debe encadenar el método session() a delete_one() 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(doc! {
            "name": "Sula",
            "author": "Toni Morrison"
        })
        .session(&mut *session)
        .await?;
    films_coll
        .insert_one(doc! {
            "name": "Nostalgia",
            "year": 1983
        })
        .session(&mut *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().
Llama al método start_transaction() para iniciar una transacción.
Llama al método and_run() para ejecutar la función de retorno insert_media() dentro de la transacción.

let mut session = client.start_session().await?;
session
    .start_transaction()
    .and_run((), |session, _| insert_media(session).boxed())
    .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.

Nota

Operaciones paralelas no admitidas

El controlador de Rust no soporta la ejecución de operaciones paralelas dentro de una sola transacción.

Si utilizas MongoDB Server v8.0 o una versión posterior, puedes realizar operaciones de escritura en múltiples espacios de nombres dentro de una única transacción utilizando operaciones de escritura por lotes. Para obtener más información, consulte la guía de operaciones masivas.

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

Operaciones de escritura masiva

Operaciones compuestas