mysqli_begin_transaction — Funktion · PHP-Referenz

Signatur

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

Beschreibung

mysqli_begin_transaction() leitet eine Transaktion auf einer bestehenden MySQL/MariaDB-Verbindung ein. Alle nachfolgenden SQL-Anweisungen werden erst dann dauerhaft in der Datenbank gespeichert, wenn explizit mysqli_commit() aufgerufen wird. Mit mysqli_rollback() lassen sich alle Änderungen seit Transaktionsbeginn rückgängig machen.

Die Funktion setzt voraus, dass die verwendete Datenbank-Engine Transaktionen unterstützt — bei MySQL und MariaDB ist das primär InnoDB. Bei MyISAM-Tabellen werden Aufrufe dieser Funktion still ignoriert, ohne einen Fehler auszulösen.

Über den Parameter $flags kann das Verhalten der Transaktion gesteuert werden, beispielsweise mit MYSQLI_TRANS_START_READ_ONLY für schreibgeschützte Transaktionen oder MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT für konsistente Leseansichten. Der optionale Parameter $name ermöglicht benannte Transaktionen als Savepoints.

Diese Funktion entspricht dem prozeduralen Äquivalent zur objektorientierten Methode mysqli::begin_transaction() und ergänzt das Trio aus mysqli_commit() und mysqli_rollback() für eine vollständige Transaktionskontrolle.

Parameter

Name	Typ	Default	Beschreibung
$mysql Pflicht	mysqli		Eine aktive `mysqli`-Verbindungsressource, wie sie von `mysqli_connect()` oder `mysqli_init()` zurückgegeben wird.
$flags	int	0	Optionale Kombination von Transaktions-Flags. Mögliche Werte sind `MYSQLI_TRANS_START_READ_ONLY`, `MYSQLI_TRANS_START_READ_WRITE` und `MYSQLI_TRANS_START_WITH_CONSISTENT_SNAPSHOT`. Mehrere Flags können per bitweisem OR (`\|`) kombiniert werden.
$name	?string	null	Optionaler Name für die Transaktion (Savepoint). Wird dieser angegeben, wird intern `SAVEPOINT name` ausgeführt.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Transaktion erfolgreich gestartet wurde, andernfalls false. Im Fehlerfall sollte mysqli_error() zur Fehleranalyse verwendet werden.

Beispiele

Einfache Transaktion mit Commit und Rollback

<?php
$mysqli = mysqli_connect('localhost', 'benutzer', 'passwort', 'meine_datenbank');

if (!$mysqli) {
    die('Verbindung fehlgeschlagen: ' . mysqli_connect_error());
}

// Transaktion starten
mysqli_begin_transaction($mysqli);

try {
    mysqli_query($mysqli, "INSERT INTO konten (benutzer_id, betrag) VALUES (1, -100.00)");
    mysqli_query($mysqli, "INSERT INTO konten (benutzer_id, betrag) VALUES (2, 100.00)");

    // Fehlerprüfung
    if (mysqli_errno($mysqli)) {
        throw new RuntimeException('SQL-Fehler: ' . mysqli_error($mysqli));
    }

    // Transaktion bestätigen
    mysqli_commit($mysqli);
    echo 'Überweisung erfolgreich durchgeführt.';
} catch (RuntimeException $e) {
    // Bei Fehler: alle Änderungen zurückrollen
    mysqli_rollback($mysqli);
    echo 'Fehler – Transaktion zurückgerollt: ' . $e->getMessage();
}

mysqli_close($mysqli);

Überweisung erfolgreich durchgeführt.

Schreibgeschützte Transaktion mit Flag

<?php
$mysqli = new mysqli('localhost', 'benutzer', 'passwort', 'meine_datenbank');

// Schreibgeschützte Transaktion starten
mysqli_begin_transaction($mysqli, MYSQLI_TRANS_START_READ_ONLY);

$result = mysqli_query($mysqli, 'SELECT id, name, kontostand FROM kunden WHERE aktiv = 1');

while ($zeile = mysqli_fetch_assoc($result)) {
    echo $zeile['name'] . ': ' . $zeile['kontostand'] . ' EUR' . PHP_EOL;
}

// Transaktion beenden (kein Commit nötig bei Read-Only)
mysqli_commit($mysqli);

mysqli_close($mysqli);

// Wichtig · Fallstricke

Autocommit: mysqli_begin_transaction() deaktiviert intern das Autocommit für die Dauer der Transaktion. Nach einem mysqli_commit() oder mysqli_rollback() wird der vorherige Autocommit-Modus wiederhergestellt. Wer explizit mysqli_autocommit($mysqli, false) verwendet, sollte beachten, dass das Verhalten kombiniert auftreten kann.

Engine-Unterstützung: Nur transaktionsfähige Engines wie InnoDB unterstützen Transaktionen vollständig. Bei MyISAM-Tabellen werden SQL-Anweisungen sofort und unwiderruflich ausgeführt, auch wenn eine Transaktion aktiv ist.

Fehlerbehandlung: mysqli_query() gibt bei einem Fehler false zurück, wirft aber keine Exception. Es empfiehlt sich, mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT) zu aktivieren, damit Fehler automatisch als Exceptions geworfen werden — so ist die Nutzung in einem try/catch-Block deutlich sicherer.

Siehe auch

mysqli_commit mysqli_rollback mysqli_autocommit mysqli_savepoint mysqli_release_savepoint PDO::beginTransaction