Transacciones

Coherencia causal

MongoDB habilita la coherencia causal en ciertas sesiones de clientes. El modelo de coherencia causal garantiza que en un sistema distribuido, las operaciones dentro de una sesión se ejecuten en un orden causal. Los clientes observan resultados que son coherentes con las relaciones causales, o las dependencias entre las operaciones. Por ejemplo, si realizas una serie de operaciones donde una depende lógicamente del resultado de otra, las lecturas subsecuentes reflejarán esa relación de dependencia.

Para garantizar la coherencia causal, las sesiones de los clientes deben cumplir los siguientes requisitos:

• Al iniciar una sesión, el controlador debe habilitar la opción de consistencia causal. Esta opción está habilitada por defecto.

• Las operaciones deben ejecutarse en una sola sesión en un solo hilo. De lo contrario, las sesiones o hilos deben comunicarse entre sí el tiempo de operación y los valores de tiempo del clúster. Para ver un ejemplo de dos sesiones que comunican estos valores, consulta Ejemplos de consistencia causal en el manual del servidor MongoDB.

• Debes utilizar una preocupación de lectura mongocxx::read_concern::level::k_majority.

• Debe usar un mongocxx::write_concern::level::k_majority nivel de confirmación de escritura (write concern). Este es el valor predeterminado de nivel de confirmación de escritura (write concern).

La siguiente tabla describe las garantías que brindan las sesiones causalmente consistentes:

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:

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

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

3. Crea un objeto de opción para preparar la configuración de la preocupación de escritura para las operaciones de transacción. Para obtener más información sobre la semántica de lectura y escritura, consulte la sección "Preferencia de lectura/Preferencia de escritura/Preferencia de lectura" del manual 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;

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 API principales proporcionados por la interfaz mongocxx::client_session:

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 la configuración de la preocupación de escritura para las operaciones de transacción. Para obtener más información sobre la semántica de lectura y escritura, consulte la sección "Preferencia de lectura/Preferencia de escritura/Preferencia de lectura" del manual 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;
}

Documentación de la API

Para obtener más información sobre cualquiera de los tipos o métodos analizados en esta guía, consulte la siguiente documentación de API:

• mongocxx::client

• mongocxx::sesión_de_cliente

• mongocxx::opciones::transacción

• inicio_sesión()

• with_transaction()

• iniciar_transacción()

• commit_transaction()

• abort_transaction()

• insert_one()