rollback

Introdução

MySQLi é a extensão PHP usada para se comunicar com bancos de dados MySQL. A função mysqli_rollback() (ou o método $mysqli->rollback() no estilo orientado a objetos) desfaz todas as alterações realizadas desde o início de uma transação. Esta página explica quando e por que você precisa dela, como ela se encaixa ao lado de mysqli_commit(), e apresenta exemplos executáveis nos estilos procedural e orientado a objetos.

Se você é novo na extensão, comece com PHP MySQLi e conectando ao MySQL.

O que é a função Rollback do MySQLi?

Uma transação é um grupo de operações de banco de dados tratadas como uma única unidade de trabalho: ou todas são aplicadas, ou nenhuma é. mysqli_rollback() é o que torna possível "nenhuma delas" — ela descarta todas as alterações feitas desde o início da transação e retorna o banco de dados ao seu estado anterior.

O exemplo clássico é uma transferência de dinheiro. Subtrair de uma conta e adicionar a outra devem acontecer juntos; se a segunda consulta falhar, você não pode deixar a primeira aplicada. Fazer o rollback garante que os registros permaneçam equilibrados.

bool mysqli_rollback(mysqli $mysql, int $flags = 0, ?string $name = null)

Ela retorna true em caso de sucesso e false em caso de falha. O parâmetro opcional $name permite fazer rollback para um savepoint nomeado em vez da transação inteira.

Autocommit: por que você precisa de transações

Por padrão, o MySQL é executado no modo autocommit, o que significa que cada instrução individual é confirmada imediatamente e permanentemente — não há nada para desfazer. Chamar mysqli_begin_transaction() desativa o autocommit durante a transação, de modo que suas alterações permaneçam pendentes até que você execute explicitamente commit() ou rollback(). Consulte autocommit para o comportamento completo.

Como funciona o fluxo de rollback

Uma transação completa segue quatro etapas:

1. Conectar ao servidor.
2. Iniciar uma transação com mysqli_begin_transaction().
3. Executar suas consultas.
4. Confirmar se tudo foi bem-sucedido, ou fazer rollback se algo falhar.

Aqui está um exemplo procedural completo:

<?php
// Create a connection to the MySQL server
$conn = mysqli_connect("localhost", "username", "password", "database");

// Check connection
if (!$conn) {
    die("Connection failed: " . mysqli_connect_error());
}

// Start a transaction
mysqli_begin_transaction($conn);

// Execute queries and make changes to the database
$insert = mysqli_query($conn, "INSERT INTO `my_table` (column1, column2) VALUES ('value1', 'value2')");
$update = mysqli_query($conn, "UPDATE `my_table` SET column1 = 'new_value' WHERE id = 1");

// Check if queries succeeded
if ($insert && $update) {
    // Commit the transaction if all queries succeed
    mysqli_commit($conn);
    echo "Transaction committed successfully.";
} else {
    // Rollback the changes if any query fails
    mysqli_rollback($conn);
    echo "Transaction failed and rolled back: " . mysqli_error($conn);
}

mysqli_close($conn);
?>

Uma transação é iniciada, duas consultas são executadas, e o resultado determina o desfecho: confirmar em caso de sucesso, fazer rollback em caso de falha. Observe que mysqli_query() só retorna false quando uma consulta falha no nível SQL — ela não lança exceções, então você deve verificar o valor de retorno por conta própria, a menos que habilite exceções (demonstrado abaixo).

Estilo orientado a objetos com prepared statements

A maioria do código em produção usa a API orientada a objetos junto com prepared statements, que previnem injeção SQL separando a consulta dos seus dados. Ativar o modo de relatório de exceções permite envolver toda a transação em um único try/catch e fazer rollback de um único lugar:

<?php
// Throw exceptions on any MySQLi error instead of returning false
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$mysqli = new mysqli("localhost", "username", "password", "database");

$mysqli->begin_transaction();

try {
    $stmt = $mysqli->prepare("UPDATE accounts SET balance = balance - ? WHERE id = ?");
    $stmt->bind_param("di", $amount, $fromId);
    $amount = 100.00;
    $fromId = 1;
    $stmt->execute();

    $stmt = $mysqli->prepare("UPDATE accounts SET balance = balance + ? WHERE id = ?");
    $stmt->bind_param("di", $amount, $toId);
    $toId = 2;
    $stmt->execute();

    // Both updates succeeded — make them permanent
    $mysqli->commit();
    echo "Transfer committed.";
} catch (mysqli_sql_exception $e) {
    // Anything threw — undo everything
    $mysqli->rollback();
    echo "Transfer failed and rolled back: " . $e->getMessage();
}

$mysqli->close();
?>

Como MYSQLI_REPORT_STRICT faz com que instruções com falha lancem mysqli_sql_exception, você nunca precisa testar o valor de retorno de cada consulta — o bloco catch lida com todos os caminhos de erro. Consulte exceções PHP para mais informações sobre try/catch.

Fazendo rollback para um savepoint

Um savepoint é um marcador nomeado dentro de uma transação. Fazer rollback para ele desfaz apenas o trabalho realizado após o savepoint, deixando as alterações anteriores pendentes. Isso é útil quando parte de uma transação é opcional:

<?php
$mysqli->begin_transaction();

$mysqli->query("INSERT INTO orders (customer_id) VALUES (5)");
$mysqli->savepoint("after_order");

$mysqli->query("INSERT INTO order_items (order_id, sku) VALUES (LAST_INSERT_ID(), 'BAD')");

// Undo only the order_items insert; the order row remains pending
$mysqli->rollback(0, "after_order");

$mysqli->commit(); // commits the order without the bad item
?>

Casos de uso da função Rollback do MySQLi

A função Rollback do MySQLi é útil para uma variedade de cenários, incluindo:

1. Integridade de dados

Mantém a consistência do banco de dados revertendo atualizações parciais quando uma operação falha, garantindo que os registros permaneçam válidos.

2. Tratamento de erros

Fornece um mecanismo de recuperação limpo. Quando ocorre uma falha, fazer rollback evita dados órfãos ou corrompidos, permitindo que a aplicação registre e exiba mensagens de erro significativas.

3. Gerenciamento de transações

Simplifica o controle do fluxo de trabalho, permitindo que os desenvolvedores abortem uma sequência de operações dependentes e reiniciem ou abandonem com segurança a transação sem limpeza manual.

Vantagens da função Rollback do MySQLi

A função Rollback do MySQLi oferece vários benefícios técnicos para desenvolvedores PHP:

1. Atomicidade

Garante que um grupo de operações de banco de dados seja bem-sucedido em conjunto ou falhe em conjunto, evitando atualizações parciais que poderiam corromper dados.

2. Depuração simplificada

Quando uma transação falha, fazer rollback restaura o banco de dados ao seu estado anterior, facilitando isolar e corrigir a consulta problemática sem limpeza manual.

3. Otimização de desempenho

Agrupar múltiplas consultas em uma única transação reduz a sobrecarga de confirmar alterações individualmente, resultando em operações de banco de dados mais rápidas.

Armadilhas comuns

• O mecanismo de armazenamento importa. Apenas mecanismos transacionais suportam rollback. O InnoDB padrão do MySQL suporta; o mecanismo mais antigo MyISAM ignora silenciosamente as transações, então um rollback nele não altera nada. Certifique-se de que suas tabelas sejam InnoDB.
• Instruções DDL fazem autocommit. Instruções como CREATE TABLE, ALTER TABLE e DROP TABLE confirmam implicitamente a transação atual no MySQL — você não pode desfazê-las. Mantenha alterações de esquema fora de transações que você pretende desfazer.
• Faça rollback exatamente uma vez. Após um commit() ou um rollback() completo, a transação terminou. Inicie uma nova antes de executar mais trabalho transacional.
• Quedas de conexão fazem rollback automático. Se a conexão for perdida no meio de uma transação, o MySQL faz rollback automaticamente — o trabalho não confirmado nunca é deixado parcialmente aplicado.

Conclusão

A função mysqli_rollback() é essencial para desenvolvedores PHP que precisam reverter alterações no banco de dados durante uma transação. Ela garante a integridade dos dados, simplifica o gerenciamento de transações e melhora o tratamento de erros. Seguindo as etapas deste guia, os desenvolvedores podem implementar rollbacks com segurança para manter operações de banco de dados confiáveis.

Prática