/ /

Transações e Sessões

Visão geral

Neste guia, você pode aprender como usar a biblioteca PHP do MongoDB para executar transações. As transações permitem que você execute uma série de operações que alteram os dados somente se toda a transação estiver confirmada. Se alguma operação na transação não for bem-sucedida, a biblioteca interromperá a transação e descartará todas as alterações de dados antes que elas se tornem visíveis. Esse recurso é chamado de atomicidade.

No MongoDB, a transação é executada dentro de sessões lógicas. Uma sessão é um agrupamento de operações de leitura ou escrita relacionadas que você deseja executar sequencialmente. As sessões habilitam a consistência causal para um grupo de operações e permitem que você execute operações em uma transação compatível com ACID , que é uma transação que atende a uma expectativa de atomicidade, consistência, isolamento e durabilidade. O MongoDB garante que os dados envolvidos em suas operações de transação permaneçam consistentes, mesmo que as operações encontrem erros inesperados.

Ao usar a Biblioteca PHP do MongoDB , você pode criar uma nova sessão a partir de uma instância MongoDB\Client . Em seguida, você pode utilizar a instância do MongoDB\Driver\Session resultante para executar transações.

Aviso

Use um Session somente em operações executadas no Client que o criou. Utilizar uma Session com um Client diferente resulta em erros de operação.

Consistência causal

O MongoDB permite consistência causal em determinadas sessões de cliente. O modelo de consistência causal garante que, em um sistema distribuído, as operações dentro de uma sessão sejam executadas em uma ordem causal. Os clientes observam resultados consistentes com as relações causais ou as dependências entre as operações. Por exemplo, se você executar uma série de operações em que uma operação depende logicamente do resultado de outra, todas as leituras subsequentes refletirão o relacionamento de dependência .

Para garantir a consistência causal, as sessões de cliente devem atender aos seguintes requisitos:

Ao iniciar uma sessão, o driver deve habilitar a opção de consistência causal. Esta opção está habilitada por padrão.
As operações devem ser executadas em uma única sessão em um único thread. Caso contrário, as sessões ou threads devem comunicar os valores de optime e tempo de cluster uns aos outros. Para exibir um exemplo de duas sessões que comunicam esses valores, consulte os exemplos de Consistência causal no manual do MongoDB Server.
Você deve usar uma preocupação de leitura majority .
Você deve usar uma preocupação de gravação majority . Este é o valor padrão de preocupação de gravação .

A tabela a seguir descreve as garantias que as sessões causalmente consistentes oferecem:

Garantia	Descrição
Ler suas gravações	As operações de leitura refletem os resultados das operações de gravação anteriores.
Leituras monotônicas	As operações de leitura não retornam resultados que reflitam um estado de dados anterior a uma operação de leitura anterior.
Escritas monotônicas	Se uma operação de gravação precisar preceder outras operações de gravação, o servidor executará essa operação de gravação primeiro. Por exemplo, se você chamar `MongoDB\Collection::insertOne()` para inserir um documento e, em seguida, chamar `MongoDB\Collection::updateOne()` para modificar o documento inserido, o servidor executará a operação de inserção primeiro.
Escritas que seguem as leituras	Se uma operação de gravação precisar seguir outras operações de leitura, o servidor executará primeiro as operações de leitura. Por exemplo, se você chamar `MongoDB\Collection::findOne()` para recuperar um documento e, em seguida, chamar `MongoDB\Collection::deleteOne()` para excluir o documento recuperado, o servidor executará primeiro a operação de localização.

Dica

Para saber mais sobre os conceitos mencionados nesta seção, consulte as seguintes entradas de manual do MongoDB Server :

APIs de transações

Nesta seção, você pode aprender sobre as APIs de transação fornecidas pela Biblioteca PHP do MongoDB . Antes de iniciar uma transação, você deve criar um Session utilizando o método MongoDB\Client::startSession() na sua instância do Client . Em seguida, você pode usar uma das seguintes APIs para realizar uma transação:

Convenient API

A biblioteca PHP do MongoDB fornece uma Convenient Transaction API para gerenciar o ciclo de vida das transações. Implemente essa API usando a função MongoDB\with_transaction() para executar uma chamada de resposta de resposta personalizada em uma transação. A função with_transaction() executa as seguintes tarefas:

Inicia a transação
Lida com erros encerrando a transação ou tentando novamente, como quando a operação retorna um TransientTransactionError
Confirma a transação

A seção Exemplo de transação deste guia demonstra como usar essa API para realizar uma transação.

Core API

Como alternativa, você pode ter mais controle sobre o ciclo de vida da transação usando os métodos fornecidos pela classe Session . A tabela a seguir descreve esses métodos:

Método	Descrição
`startTransaction()`	Inicia uma nova transação nesta sessão. A sessão deve ser passada para cada operação dentro da transação, ou a operação será executada fora da transação. Você pode definir as opções de transação passando um parâmetro de opções.
`commitTransaction()`	Confirma a transação ativa para esta sessão. Esse método retorna um erro se não houver nenhuma transação ativa para a sessão, se a transação tiver sido encerrada anteriormente ou se houver um conflito de gravação.
`abortTransaction()`	Termina a transação ativa para esta sessão. Esse método retorna um erro se não houver uma transação ativa para a sessão ou se a transação tiver sido confirmada ou encerrada.

Exemplo de transação

Este exemplo define uma função de chamada de resposta de chamada que modifica os dados nas coleções do banco de banco de dados do bank para uma transação bancária. O código executa as seguintes ações:

Cria Collection instâncias para acessar as coleções de destino.
Especifica o número da conta e o valor a ser transferido entre contas.
Define a função de chamada de resposta de chamada, que recebe a instância Session como um parâmetro.
Atualiza os saldos do cliente para refletir a transferência de dinheiro.
Registra um recebimento da transação com um carimbo de data/hora.
Imprime uma mensagem se a transação for confirmada com sucesso.

$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;
};

Em seguida, execute o seguinte código para executar a transação. Este código conclui as seguintes ações:

Cria uma sessão a partir do cliente utilizando o método startSession() .
Chama a função with_transaction() para gerenciar a transação, passando a sessão e a chamada de resposta de resposta 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

Observação

Operações paralelas não suportadas

A biblioteca PHP não suporta a execução de operações paralelas em uma única transação.

Informações adicionais

Para saber mais sobre os conceitos mencionados neste guia, consulte as seguintes páginas no manual do MongoDB Server :

Para saber mais sobre a ACID compliance, consulte Quais são as propriedades ACID nos sistemas de gerenciamento de banco de dados? artigo no site do MongoDB .

Para saber mais sobre operações de inserção, consulte o guia Inserir documento .

Documentação da API

Para saber mais sobre os métodos e tipos mencionados neste guia, consulte a documentação da API abaixo:

Para saber mais sobre a classe e os métodos Session , consulte a seguinte documentação da API de extensão PHP:

Voltar

Operações de gravação em massa

Configurar operações CRUD