Overview
En esta guía, aprenderá a usar el controlador de Rust para realizar transacciones. Las transacciones permiten realizar una serie de operaciones que modifican los datos solo si se confirma la transacción completa. Si alguna operación de la transacción no se realiza correctamente, el controlador la detiene y descarta todos los cambios en los datos antes de que sean visibles. Esta característica 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.
Al usar el controlador Rust, puedes crear una nueva sesión desde un
Client instancia como tipo ClientSession. Puedes mejorar el rendimiento de tu aplicación reutilizando tu cliente para varias sesiones y transacciones en lugar de crear 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 |
|---|---|
| Starts a new transaction on this session. The session
must be passed into each operation within the transaction, or
the operation will run outside of the transaction. You can set transaction options by chaining TransactionOptions
option builder methods to start_transaction().Errors returned from operations run within the transaction
might include a TRANSIENT_TRANSACTION_ERROR label, which
indicates that the entire transaction can be ended, then retried
with the expectation that it will succeed. |
| Commits the active transaction for this session. This method returns an
error if there is no active transaction for the session or the
transaction was previously ended. This method might return an error that includes an
UNKNOWN_TRANSACTION_COMMIT_RESULT label, which
indicates that it is unknown if the committed transaction
satisfies the set write concern. If you encounter this error,
it is safe to retry the commit until the write concern is
satisfied or the method returns an error without the label. |
| Ends the active transaction for this session. This method returns an
error if there is no active transaction for the session or if the
transaction was committed or ended. |
| Runs the given callback, then commits or ends the transaction. The
driver retries callbacks and commits that raise an error with a
TRANSIENT_TRANSACTION_ERROR label. If they raise any
other error, the driver ends the transaction and returns the error
to the caller. When you use this method to perform a transaction,
the driver automatically handles any errors, so you can choose to omit
error handling code.Because the callback returns a future and can be run multiple
times, the Rust language closure borrowing rules for captured
values can be restrictive. So, the and_run()
method accepts a context parameter that is passed to the callback.Parameters: context C, callback FnMut(&'a mut
ClientSession, &'a mut C) |
Importante
Métodos que pueden ejecutarse 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 retornoinsert_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 necesitas más control sobre tus transacciones, consulta la Documentación de la API de ClientSession para encontrar un ejemplo que muestre cómo crear y confirmar una transacción manualmente.
Nota
Operaciones paralelas no admitidas
El controlador de Rust no soporta la ejecución de operaciones paralelas dentro de una sola transacción.
Si utiliza MongoDB Server v8.0 o posterior, puede realizar operaciones de escritura en varios espacios de nombres dentro de una sola transacción mediante operaciones de escritura masiva. Para obtener más información, consulte Guía sobre operaciones en bloque.
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: