/ /

Transacciones y Sesiones

Overview

En esta guía, aprenderá a usar la biblioteca PHP de MongoDB 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, la biblioteca 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 utilizar la biblioteca PHP de MongoDB, puede crear una nueva sesión desde una MongoDB\Client instancia. Luego, puede usar la instancia MongoDB\Driver\Session resultante para realizar transacciones.

Advertencia

Use un Session solo en operaciones que se ejecuten en el Client que lo creó. Usar un Session con un Client diferente genera errores de operación.

Coherencia causal

MongoDB permite la consistencia causal en ciertas sesiones de cliente. El modelo de consistencia causal garantiza que, en un sistema distribuido, las operaciones dentro de una sesión se ejecuten en un orden causal. Los clientes observan resultados consistentes con las relaciones causales o las dependencias entre operaciones. Por ejemplo, si se realiza una serie de operaciones donde una depende lógicamente del resultado de otra, las lecturas posteriores reflejan la 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 subproceso. De lo contrario, las sesiones o subprocesos deben comunicarse entre sí los valores de tiempo de la operación y del clúster. Para ver un ejemplo de dos sesiones que comunican estos valores, consulte Ejemplos de consistencia causal en el manual del servidor MongoDB.
Debes utilizar una preocupación de lectura majority.
Debe usar un 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:

Garantía	Descripción
Leer las escrituras	Las operaciones de lectura reflejan los resultados de las operaciones de escritura anteriores.
Lecturas monotónicas	Las operaciones de lectura no devuelven resultados que reflejen un estado de datos anterior al de una operación de lectura anterior.
Escrituras monotónicas	Si una operación de escritura debe preceder a otras operaciones de escritura, el servidor ejecuta esta operación de escritura primero. Por ejemplo, si llama a `MongoDB\Collection::insertOne()` para insertar un documento y luego llama a `MongoDB\Collection::updateOne()` para modificar el documento insertado, el servidor ejecuta primero la operación de inserción.
Las escrituras siguen a las lecturas	Si una operación de escritura debe seguir a otras operaciones de lectura, el servidor ejecuta primero las operaciones de lectura. Por ejemplo, si llama a `MongoDB\Collection::findOne()` para recuperar un documento y luego llama a `MongoDB\Collection::deleteOne()` para eliminar el documento recuperado, el servidor ejecuta primero la operación de búsqueda.

Tip

Para obtener más información sobre los conceptos mencionados en esta sección, consulte las siguientes entradas del manual de MongoDB Server:

API de transacciones

En esta sección, aprenderá sobre las API de transacciones que ofrece la biblioteca PHP de MongoDB. Antes de iniciar una transacción, debe crear un Session mediante el método MongoDB\Client::startSession() en su instancia Client. Después, puede usar cualquiera de las siguientes API para realizar una transacción:

Convenient API
Core API

Convenient API

La biblioteca PHP de MongoDB proporciona una práctica API de transacciones para gestionar el ciclo de vida de las transacciones. Implemente esta API usando la MongoDB\with_transaction() función para ejecutar una devolución de llamada personalizada dentro de una transacción. La with_transaction() función realiza las siguientes tareas:

Inicia la transacción
Maneja los errores finalizando la transacción o reintentándola, como cuando la operación devuelve un TransientTransactionError
Confirma la transacción

La sección Ejemplo de transacción de esta guía demuestra cómo utilizar esta API para realizar una transacción.

Core API

Como alternativa, puede tener mayor control sobre el ciclo de vida de sus transacciones utilizando los métodos proporcionados por la clase Session. La siguiente tabla describe estos métodos:

Método	Descripción
`startTransaction()`	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 passing an options parameter.
`commitTransaction()`	Commits the active transaction for this session. This method returns an error if there is no active transaction for the session, the transaction was previously ended, or if there is a write conflict.
`abortTransaction()`	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.

Ejemplo de transacción

Este ejemplo define una función de devolución de llamada que modifica los datos de las colecciones de la base de datos bank para una transacción bancaria. El código realiza las siguientes acciones:

Crea Collection instancias para acceder a las colecciones de destino.
Especifica el número de cuenta y el monto que se transferirá entre cuentas.
Define la función de devolución de llamada, que recibe la instancia Session como parámetro.
Actualiza los saldos del cliente para reflejar la transferencia de dinero.
Registra un recibo de la transacción con una marca de tiempo.
Imprime un mensaje si la transacción se realizó correctamente.

$receipts = $client->bank->receipts;
$checking = $client->bank->checking_accounts;
$saving = $client->bank->saving_accounts;
$accountId = '5678';
$transferAmount = 1000.0;
$callback = function (MongoDB\Driver\Session $session) use (
    $checking,
    $saving,
    $receipts,
    $accountId,
    $transferAmount,
): void {
    $checking->updateOne(
        ['account_id' => $accountId],
        ['$inc' => ['balance' => -$transferAmount]],
        ['session' => $session],
    );
    $saving->updateOne(
        ['account_id' => $accountId],
        ['$inc' => ['balance' => $transferAmount]],
        ['session' => $session],
    );
    $summary = sprintf('SAVINGS +%1$u CHECKING -%1$u', $transferAmount);
    $receipts->insertOne(
        [
            'account_id' => $accountId,
            'summary' => $summary,
            'timestamp' => new MongoDB\BSON\UTCDateTime(),
        ],
        ['session' => $session],
    );
    echo 'Successfully performed transaction!', PHP_EOL;
    echo 'Summary: ', $summary, PHP_EOL;
};

Luego, ejecute el siguiente código para realizar la transacción. Este código realiza las siguientes acciones:

Crea una sesión desde el cliente utilizando el método startSession().
Llama a la función with_transaction() para gestionar la transacción, pasando la sesión y la devolución de llamada como parámetros.

$session = $client->startSession();
try {
    MongoDB\with_transaction($session, $callback);
} catch (MongoDB\Driver\Exception\RuntimeException $e) {
    echo 'Caught exception: ', $e->getMessage(), PHP_EOL;
}

Successfully performed transaction!
Summary: SAVINGS +1000 CHECKING -1000

Nota

Operaciones paralelas no admitidas

La biblioteca PHP no admite la ejecución de operaciones paralelas dentro de una sola transacción.

Si está utilizando la biblioteca PHP v2.1 o posterior y MongoDB Server v8.0 o posterior, puede realizar operaciones de escritura en múltiples espacios de nombres dentro de una sola transacción utilizando el MongoDB\Client::bulkWrite() Método. Para obtener más información, consulte Operaciones de escritura masiva.

Información Adicional

Para obtener más información sobre los conceptos mencionados en esta guía, consulte las siguientes páginas del manual de MongoDB Server:

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:

Para obtener más información sobre la clase Session y los métodos, consulte la siguiente documentación de la API de extensión PHP:

Volver

Operaciones de escritura masiva

Configurar las operaciones CRUD