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 una agrupación de operaciones de lectura o escritura relacionadas que se ejecutan secuencialmente. Las sesiones permiten la consistencia causal de un grupo de operaciones y ejecutar operaciones en una transacción compatible con ACID, que cumple con los requisitos de atomicidad, consistencia, aislamiento y durabilidad. MongoDB garantiza que los datos involucrados en las transacciones se mantengan consistentes, incluso si se producen errores inesperados.
Al usar el controlador Rust, puede crear una nueva sesión desde un
Client Instancia como tipo ClientSession. Puedes mejorar el rendimiento de tu aplicación reutilizando tu cliente para múltiples sesiones y transacciones en lugar de instanciar un nuevo cliente cada vez.
Advertencia
Use un ClientSession solo en operaciones que se ejecuten en el Client que lo creó. Usar un ClientSession con un Client diferente genera errores de operación.
Métodos
Cree un ClientSession con el método start_session() en su instancia Client. A continuación, puede modificar el estado de la sesión con 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, debe encadenar el método session() a la operación. Este método acepta una instancia ClientSession como parámetro.
Por ejemplo, para eliminar un documento, generalmente se puede usar el método delete_one(). Sin embargo, para eliminar un documento dentro de una transacción, se 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 devolución de llamada insert_media() que inserta 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 devolución de llamadainsert_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 necesita más control sobre sus transacciones, consulte la Documentación de la 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 Rust no admite 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 deoperaciones masivas.
Información Adicional
Para obtener más información sobre los conceptos mencionados en esta guía, consulte las siguientes páginas del manual del servidor:
Para obtener más información sobre el cumplimiento de ACID, consulte el artículo ¿Qué son las propiedades ACID en los sistemas de administración de bases de datos? en el sitio web de MongoDB.
Para obtener más información sobre las operaciones de inserción, consulte la guía Insertar documentos.
Documentación de la API
Para obtener más información sobre los métodos y tipos mencionados en esta guía, consulte la siguiente documentación de API: