Join us at MongoDB.local London on 7 May to unlock new possibilities for your data. Use WEB50 to save 50%.
Register now >
Docs Menu
Docs Home
/ /

Transacciones

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.

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.

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:

  1. Inicia una sesión desde el cliente usando el método start_session().

  2. Define una función de retorno que especifica las operaciones a realizar durante la transacción.

  3. 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.

  4. 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;

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

start_transaction()

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.

commit_transaction()

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.

abort_transaction()

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:

  1. Inicia una sesión desde el cliente usando el método start_session().

  2. 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.

  3. Llama al método start_transaction() para iniciar una transacción, pasando el objeto de opciones como argumento.

  4. 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 etiqueta TransientTransactionError, la transacción se vuelve a intentar.

  5. Confirma la transacción activa utilizando el método commit_transaction(). Si la confirmación encuentra un error con la etiqueta UnknownTransactionCommitResult, 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;
}

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.

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:

Volver

GridFS

En esta página