/ /

Transacciones

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.

Cuando utilice el controlador C++, puede crear una nueva sesión a partir de una instancia de mongocxx::client. A continuación, puedes utilizar la instancia de 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 los hilos. Cada instancia de mongoxcc::client y sus instancias subordinadas, incluidas mongocxx::client_session, debe ser utilizada por un solo hilo a la vez. Para obtener más información, consulta la guía Seguridad de subprocesos 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
`start_transaction()`	Inicia una nueva transacción en la sesión actual del cliente. Acepta una `mongocxx::options::transaction` instancia opcional de como argumento para configurar las opciones. Para ver la lista completa de opciones, consulte mongocxx::options::transaction en la documentación de la API. Genera una excepción si las opciones están mal configuradas, si hay fallos de red u otros fallos transitorios, o si hay otros errores, como una sesión con una transacción ya en curso. Si se devuelve un error con la `TransientTransactionError` etiqueta, puede finalizar la transacción y volver a intentarla con la expectativa de que se complete con éxito. Para obtener más información sobre este método, consulte la guía startTransaction() en el manual del servidor MongoDB.
`commit_transaction()`	Confirma la transacción activa en la sesión actual del cliente. Genera una excepción si las opciones están mal configuradas, si hay fallos de red u otros fallos transitorios, o si hay otros errores, como una sesión sin ninguna transacción en curso. Si se devuelve un error con la `UnknownTransactionCommitResult` etiqueta, puede finalizar la transacción y volver a intentarla con la expectativa de que se complete con éxito cuando la transacción confirmada satisfaga la condición de escritura establecida. Para obtener más información sobre este método, consulte la guía commitTransaction() en el manual del servidor MongoDB.
`abort_transaction()`	Finaliza la transacción activa en la sesión actual del cliente. Genera una excepción si las opciones están mal configuradas o si se producen otros errores, como una sesión sin ninguna transacción en curso. Para obtener más información sobre este método, consulte la guía `abortTransaction()` en el manual del servidor MongoDB.

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 etiqueta TransientTransactionError, 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 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;
}

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:

Volver

GridFS

Bases de datos y colecciones