Overview
En esta guía, puedes aprender a utilizar el Driver C++ de MongoDB para realizar transacciones. Las transacciones permiten ejecutar una serie de operaciones que no alteran ningún dato hasta que la transacción se confirma. 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 hagan visibles.
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 tienes la intención de ejecutar secuencialmente. Las sesiones permiten la coherencia causal para un grupo de operaciones en una transacción compatible con ACID, que es una transacción que cumple con la expectativa de atomicidad, coherencia, aislamiento y durabilidad. MongoDB garantiza que los datos involucrados en sus operaciones de transacción permanecen coherentes, incluso si las operaciones encuentran errores inesperados.
Al usar el controlador C++, puedes crear una nueva sesión desde un mongocxx::client instancia. Después, podrás usar la instancia mongocxx::client_session resultante para realizar transacciones. Se recomienda reutilizar el cliente para varias sesiones y tramitaciones en lugar de crear uno nuevo cada vez.
Advertencia
Usa un mongocxx::client_session solo con el mongocxx::client que lo creó. Utilizar un client_session con un client diferente provoca errores de operación.
Importante
Las instancias de mongocxx::client no son seguras para hilos. Cada instancia de mongoxcc::client y sus instancias secundarias, incluyendo mongocxx::client_session, deben ser usadas por un solo hilo a la vez. Para aprender más, consulta el Guía Seguridad en hilos y bifurcaciones.
APIs de transacciones
El driver de MongoDB C++ proporciona una Callback API y una Core API para gestionar el ciclo de vida de una transacción. Antes de iniciar una transacción, debes llamar al método start_session() para instanciar un mongocxx::client_session. Luego, puedes utilizar cualquiera de las siguientes API para realizar una transacción:
Callback API: API de alto nivel que maneja el ciclo de vida de la transacción e incorpora automáticamente lógica de manejo de errores.
Core API: API de bajo nivel que te permite gestionar el ciclo de vida de la transacción y crear lógica personalizada de manejo de errores.
Tip
Para obtener más información sobre la gestión de errores, consulta la sección Gestión de errores de transacciones en el manual de MongoDB Server.
Callback API
Utiliza la Callback API para permitir que el driver en C++ de MongoDB administre el ciclo de vida de tu transacción. Para implementar esta API, llama al método with_transaction() en tu mongocxx::client_session e introduce una función de retorno que especifique la secuencia de operaciones que deseas ejecutar. El método with_transaction() inicia una transacción, ejecuta la función de retorno y, o bien confirma tu transacción o la finaliza si encuentra un error. Si la transacción encuentra un error TransientTransactionError o UnknownTransactionCommitResult, el método with_transaction() vuelve a ejecutar la transacción.
El siguiente código utiliza la API de callback para realizar una transacción que inserta documentos en las colecciones movies y comments en la base de datos sample_mflix. Este código realiza las siguientes acciones:
Inicia una sesión desde el cliente usando el método
start_session().Define una función de retorno que especifica las operaciones a realizar durante la transacción.
Crea un objeto de opción para preparar el establecimiento del nivel de confirmación de escritura (write concern) en las operaciones de la transacción. Para obtener más información sobre las semánticas de lectura y escritura, consulta la sección nivel de consistencia de lectura/nivel de confirmación de escritura (write concern)/preferencia de lectura en el manual del servidor de MongoDB Server.
Llama al método
with_transaction()para gestionar la transacción, pasando la función de retorno y el objeto de opciones como argumentos.
// Establish a connection to the MongoDB deployment mongocxx::instance instance{}; mongocxx::client client(mongocxx::uri{"<connectionString>"}); // Define database and collection variables auto db = client["sample_mflix"]; auto movies_collection = db["movies"]; auto comments_collection = db["comments"]; // Define a callback specifying the sequence of operations to perform during the transaction mongocxx::client_session::with_transaction_cb callback = [&](mongocxx::client_session* session) { // Important:: You must pass the session to the operations. movies_collection.insert_one(*session, make_document(kvp("title", "Parasite"))); comments_collection.insert_one(*session, make_document(kvp("name", "Anjali Patel"), kvp("text", "This is my new favorite movie!"))); }; // Define an options instance to explicitly set the write concern for the transaction operations mongocxx::options::transaction opts; mongocxx::write_concern wc; wc.acknowledge_level(mongocxx::write_concern::level::k_majority); opts.write_concern(wc); // Start a client session auto session = client.start_session(); try { // Start a transaction, execute the operations in the callback function, and commit the results session.with_transaction(callback, opts); } catch (const mongocxx::exception& e) { std::cout << "An exception occurred: " << e.what() << std::endl; return EXIT_FAILURE; } return EXIT_SUCCESS;
Core API
Utilice la Core API para gestionar el ciclo de vida de su transacción. Para implementar esta API, debes realizar llamadas explícitas a los métodos de la interfaz mongocxx::client_session para iniciar una transacción, confirmar una transacción activa y finalizar una transacción si ocurre un error. La Core API no incorpora automáticamente la lógica de manejo de errores y, en su lugar, te permite implementar una lógica personalizada para el manejo de errores, incluidos TransientTransactionError y UnknownTransactionCommitResult.
La siguiente tabla describe los métodos Core API proporcionados por la interfaz mongocxx::client_session:
Método | Descripción |
|---|---|
| Starts a new transaction on the current client session. Accepts an optional mongocxx::options::transaction
instance as an argument to set options. For a full list of options, see mongocxx::options::transaction
in the API documentation.Raises an exception if the options are misconfigured, if there are network or other transient failures, or if there
are other errors such as a session with a transaction already in progress. If an error is returned with the TransientTransactionError label,
you can end the transaction and then retry it with the expectation that it will succeed.To learn more about this method, see the startTransaction() guide in the MongoDB Server manual. |
| Commits the active transaction on the current client session. Raises an exception if options are misconfigured, if there are network or other transient failures,
or if there are other errors such as a session with no transaction in progress. If an error is returned with the UnknownTransactionCommitResult label,
you can end the transaction and then retry it with the expectation that it will succeed when the committed transaction satisfies the set write concern.To learn more about this method, see the commitTransaction() guide in the MongoDB Server manual. |
| Ends the active transaction on the current client session. Raises an exception if the options are misconfigured or if there are other errors such as
a session with no transaction in progress. To learn more about this method, see the abortTransaction() guide in the MongoDB Server manual. |
Tip
La mongocxx::client_session clase también proporciona métodos para recuperar y modificar propiedades de la sesión. Para aprender más, consulte mongocxx::client_session en la documentación de la API.
El siguiente código utiliza la API principal para realizar una transacción que inserta documentos en las colecciones movies y comments en la base de datos sample_mflix. Este código realiza las siguientes acciones:
Inicia una sesión desde el cliente usando el método
start_session().Crea un objeto de opción para preparar el establecimiento del nivel de confirmación de escritura (write concern) en las operaciones de la transacción. Para obtener más información sobre las semánticas de lectura y escritura, consulta la sección nivel de consistencia de lectura/nivel de confirmación de escritura (write concern)/preferencia de lectura en el manual del servidor de MongoDB Server.
Llama al método
start_transaction()para iniciar una transacción, pasando el objeto de opciones como argumento.Ejecuta operaciones para insertar documentos en colecciones de la base de datos
sample_mflix, transmitiendo la sesión activa a cada operación. Si una operación encuentra un error, toda la transacción se aborta. Si el error tiene la etiquetaTransientTransactionError, la transacción se vuelve a intentar.Confirma la transacción activa utilizando el método
commit_transaction(). Si la confirmación encuentra un error con la etiquetaUnknownTransactionCommitResult, se volverá a intentar la confirmación.
// Establish a connection to the MongoDB deployment mongocxx::instance instance{}; mongocxx::client client(mongocxx::uri{"<connectionString>"}); // Runs the txn_func and retries if TransientTransactionError occurs using transaction_func = std::function<void(mongocxx::client_session& session)>; auto run_with_retry = [](transaction_func txn_func, mongocxx::client_session& session) { while (true) { try { txn_func(session); // performs transaction. break; } catch (const mongocxx::operation_exception& oe) { std::cout << "Transaction aborted. Caught exception during transaction." << std::endl; // If transient error, retry the whole transaction. if (oe.has_error_label("TransientTransactionError")) { std::cout << "TransientTransactionError, retrying transaction..." << std::endl; continue; } else { throw oe; } } } }; // Commits the active transaction and retries commit if UnknownTransactionCommitResult occurs auto commit_with_retry = [](mongocxx::client_session& session) { while (true) { try { session.commit_transaction(); // Uses write concern set at transaction start. std::cout << "Transaction committed." << std::endl; break; } catch (const mongocxx::operation_exception& oe) { // Can retry commit if (oe.has_error_label("UnknownTransactionCommitResult")) { std::cout << "UnknownTransactionCommitResult, retrying commit..." << std::endl; continue; } else { std::cout << "Error during commit..." << std::endl; throw oe; } } } }; auto txn_func = [&](mongocxx::client_session& session) { auto& client = session.client(); // Define database and collection variables auto db = client["sample_mflix"]; auto movies_collection = db["movies"]; auto comments_collection = db["comments"]; // Define an options instance to explicitly set the write concern for the transaction operations mongocxx::options::transaction opts; mongocxx::write_concern wc; wc.acknowledge_level(mongocxx::write_concern::level::k_majority); opts.write_concern(wc); session.start_transaction(opts); // Attempt to insert documents into database collections try { movies_collection.insert_one(session, make_document(kvp("title", "Parasite"))); comments_collection.insert_one(session, make_document(kvp("name", "Anjali Patel"), kvp("text", "This is my new favorite movie!"))); } catch (const mongocxx::operation_exception& oe) { std::cout << "Caught exception during transaction, aborting." << std::endl; session.abort_transaction(); throw oe; } commit_with_retry(session); }; // Start a client session auto session = client.start_session(); try { run_with_retry(txn_func, session); } catch (const mongocxx::operation_exception& oe) { // Do something with error throw oe; }
Información Adicional
Para aprender más sobre los conceptos discutidos en esta guía, consulta las siguientes páginas en el manual de MongoDB Server:
Para obtener más información sobre el cumplimiento de ACID, consulta la guía Propiedades ACID en los sistemas de gestió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 de Inserción de Documentos.
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: