Menu Docs
Página inicial do Docs
/ / /
Manual da Biblioteca PHP
/

Realizar uma transação

Nesta página

  • Visão geral
  • APIs de transações
  • Convenient API
  • Core API
  • Exemplo de transação
  • Informações adicionais
  • Documentação da API

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 utilizar a Biblioteca PHP MongoDB , você pode criar uma nova sessão a partir de uma instância do 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.

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

  • Core 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.

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()
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.

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:

  1. Cria uma sessão a partir do cliente utilizando o método startSession() .

  2. 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

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 as operações de inserção, consulte o guia Inserir documentos .

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