/ /

Transacciones y Sesiones

Overview

En esta guía, puedes aprender cómo utilizar la librería de PHP de MongoDB para realizar transacciones. Las transacciones permiten realizar una serie de operaciones que modifican datos solo si se confirma toda la transacción. Si alguna operación en la transacción no tiene éxito, la librería detiene la transacción y descarta todos los cambios de datos antes de que se vuelvan visibles. Esta funcionalidad se denomina atomicidad.

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 deseas ejecutar de manera secuencial. Las sesiones permiten la coherencia causal para un grupo de operaciones y le permiten ejecutar operaciones en una transacción compatible con ACID, que es una transacción que cumple con una expectativa de atomicidad, consistencia, aislamiento y durabilidad. MongoDB garantiza que los datos involucrados en tus operaciones de transacción permanezcan coherentes, incluso si las operaciones encuentran errores inesperados.

Cuando se utiliza la Librería PHP de MongoDB, se puede crear una nueva sesión a partir de una instancia de MongoDB\Client. Luego, puedes usar la instancia MongoDB\Driver\Session resultante para realizar transacciones.

Advertencia

Utilice un Session solo en operaciones que se ejecuten en el Client que lo creó. Usar un Session con un Client diferente da como resultado errores de operación.

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 driver debe habilitar la opción de coherencia 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í los valores de operation time y tiempo de clúster. Para ver un ejemplo de dos sesiones que comunican estos valores, consulte los Ejemplos de coherencia causal en el manual del servidor de MongoDB.
Debes usar un majority nivel de consistencia de lectura.
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 ofrecen las sesiones coherentes causales:

garantías	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 previa.
Escrituras monotónicas	Si una operación de escritura debe preceder a otras operaciones de escritura, el servidor ejecutará primero esta operación de escritura. Por ejemplo, si llamas a `MongoDB\Collection::insertOne()` para insertar un documento y luego llamas a `MongoDB\Collection::updateOne()` para modificar el documento insertado, el servidor ejecutará 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 primero ejecuta las operaciones de lectura. Por ejemplo, si llamas a `MongoDB\Collection::findOne()` para recuperar un documento y luego llamas a `MongoDB\Collection::deleteOne()` para borrar el documento recuperado, el servidor ejecutará primero la operación find.

Tip

Para aprender más sobre los conceptos mencionados en esta sección, consulta las siguientes entradas del manual del servidor MongoDB:

APIs de transacciones

En esta sección, puedes aprender sobre las APIs de transacción proporcionadas por MongoDB PHP librería. Antes de iniciar una transacción, debes crear un Session usando el método MongoDB\Client::startSession() en tu instancia Client. Entonces, puedes utilizar cualquiera de las siguientes APIs para realizar una transacción:

Convenient API
Core API

Convenient API

La Biblioteca PHP de MongoDB proporciona una API de transacciones conveniente para gestionar el ciclo de vida de las transacciones. Implemente esta API utilizando la función MongoDB\with_transaction() para ejecutar una función de retorno personalizada dentro de una transacción. La función with_transaction() realiza las siguientes tareas:

Inicia la transacción
Gestiona errores finalizando la transacción o reintentándola, como cuando la operación retorna un TransientTransactionError
Confirma la transacción

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

Core API

Alternativamente, puedes tener más control sobre el ciclo de vida de tus transacciones utilizando los métodos proporcionados por la clase Session. La siguiente tabla describe estos métodos:

Método	Descripción
`startTransaction()`	Inicia una nueva transacción en esta sesión. La sesión debe pasarse a cada operación dentro de la transacción; de lo contrario, la operación se ejecutará fuera de ella. Puede configurar las opciones de la transacción pasando un parámetro de opciones.
`commitTransaction()`	Confirma la transacción activa de esta sesión. Este método devuelve un error si no hay una transacción activa para la sesión, la transacción finalizó anteriormente o si hay un conflicto de escritura.
`abortTransaction()`	Termina la transacción activa para esta sesión. Este método devuelve un error si no hay una transacción activa para la sesión o si la transacción fue confirmada o finalizada.

Ejemplo de transacción

Este ejemplo define una función de retorno que modifica los datos en 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 retorno, 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 comprometió 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;
};

A continuación, ejecuta el siguiente código para realizar la transacción. Este código completa 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 como parámetros la sesión y la función de retorno.

$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 librería PHP no admite la ejecución de operaciones en paralelo dentro de una única transacción.

Si está utilizando la librería PHP v2.1 o posterior y el servidor MongoDB Server v8.0 o posterior, puede realizar operaciones de escritura en varios namespaces dentro de una sola transacción utilizando el método MongoDB\Client::bulkWrite(). 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, consulta las siguientes páginas del manual de MongoDB Server:

Para aprender más sobre ACID compliance, consulte el ¿Cuáles son las propiedades ACID en los sistemas de gestión de bases de datos? artículo 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 obtener más información sobre los métodos y tipos mencionados en esta guía, vea la siguiente documentación de la API:

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

Volver

Operaciones de escritura masiva

Configurar las operaciones CRUD