oci_unregister_taf_callback — Funktion · PHP-Referenz

Signatur

oci_unregister_taf_callback(resource $connection): bool

Beschreibung

oci_unregister_taf_callback() hebt die Registrierung einer Callback-Funktion auf, die zuvor mit oci_register_taf_callback() für eine Oracle-Datenbankverbindung eingerichtet wurde. Nach dem Aufruf wird kein TAF-Callback mehr ausgeführt, wenn ein Failover-Ereignis auf der Verbindung eintritt.

Transparent Application Failover (TAF) ist ein Oracle-Mechanismus, der es ermöglicht, dass eine Anwendung automatisch auf eine Ersatz-Datenbankinstanz umschaltet, wenn die primäre Instanz ausfällt. Solange ein Callback registriert ist, informiert Oracle die Anwendung über Failover-Ereignisse (Beginn, Abschluss, Fehler). Mit oci_unregister_taf_callback() wird diese Benachrichtigung deaktiviert.

Diese Funktion ist nützlich, wenn eine Verbindung nach einem bestimmten Verarbeitungsschritt in einen Zustand versetzt werden soll, in dem kein benutzerdefiniertes Failover-Verhalten mehr erwünscht ist, beispielsweise wenn die Verbindung in einen Pool zurückgegeben wird oder ein bestimmter Anwendungsabschnitt keine Failover-Logik benötigt.

Die Funktion steht nur zur Verfügung, wenn PHP mit der OCI8-Erweiterung kompiliert wurde und Oracle eine TAF-fähige Konfiguration (z. B. Oracle RAC oder Data Guard mit entsprechenden TNS-Einstellungen) verwendet.

Parameter

Name	Typ	Default	Beschreibung
$connection Pflicht	resource		Eine gültige Oracle-Verbindungsressource, die mit `oci_connect()`, `oci_new_connect()` oder `oci_pconnect()` erzeugt wurde und für die ein TAF-Callback deregistriert werden soll.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Deregistrierung des TAF-Callbacks erfolgreich war. Gibt false zurück, wenn ein Fehler auftrat, etwa weil $connection keine gültige Verbindungsressource ist.

Beispiele

TAF-Callback registrieren und anschließend deregistrieren

<?php
// Verbindung zur Oracle-Datenbank herstellen
$conn = oci_connect('benutzername', 'passwort', 'mydb_taf');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}

// TAF-Callback-Funktion definieren
function tafCallback($conn, $event, $type) {
    if ($event === OCI_FO_BEGIN) {
        echo 'Failover gestartet. Warte auf Verbindungswiederherstellung...' . PHP_EOL;
    } elseif ($event === OCI_FO_END) {
        echo 'Failover erfolgreich abgeschlossen.' . PHP_EOL;
    } elseif ($event === OCI_FO_ERROR) {
        echo 'Fehler beim Failover!' . PHP_EOL;
        return OCI_FO_RETRY;
    }
    return 0;
}

// Callback registrieren
$result = oci_register_taf_callback($conn, 'tafCallback');
if ($result) {
    echo 'TAF-Callback erfolgreich registriert.' . PHP_EOL;
}

// --- Verarbeitungslogik der Anwendung ---

// Callback nach der Verarbeitung wieder entfernen
$result = oci_unregister_taf_callback($conn);
if ($result) {
    echo 'TAF-Callback erfolgreich entfernt.' . PHP_EOL;
}

oci_close($conn);
?>

TAF-Callback erfolgreich registriert. TAF-Callback erfolgreich entfernt.

Callback bei Rückgabe an Connection-Pool entfernen

<?php
// Persistente Verbindung, die ggf. in einen Pool zurückgeht
$conn = oci_pconnect('benutzername', 'passwort', 'mydb_taf');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlspecialchars($e['message']), E_USER_ERROR);
}

function meinTafCallback($conn, $event, $type) {
    if ($event === OCI_FO_BEGIN) {
        error_log('TAF-Failover gestartet.');
    }
    return 0;
}

// Callback nur für kritische Operation registrieren
oci_register_taf_callback($conn, 'meinTafCallback');

// Kritische Datenbankoperation ausführen
$stmt = oci_parse($conn, 'SELECT sysdate FROM dual');
oci_execute($stmt);
$row = oci_fetch_array($stmt);
echo 'Aktuelles Datenbankdatum: ' . $row[0] . PHP_EOL;
oci_free_statement($stmt);

// Vor Rückgabe der Verbindung an Pool: Callback entfernen,
// damit kein Callback aus einem vorherigen Request-Kontext verbleibt
oci_unregister_taf_callback($conn);

// Verbindung wird durch PHP automatisch in den Pool zurückgegeben
?>

Aktuelles Datenbankdatum: 01-JAN-25

// Wichtig · Fallstricke

Voraussetzungen: Diese Funktion ist nur verfügbar, wenn die OCI8-Erweiterung mit einer Oracle-Clientbibliothek kompiliert wurde, die TAF unterstützt (Oracle 10g oder neuer). Außerdem muss die Oracle-Datenbank selbst TAF-fähig konfiguriert sein (z. B. über RAC oder Data Guard mit entsprechendem TNS-Eintrag).

Persistente Verbindungen: Bei persistenten Verbindungen (oci_pconnect()) ist es besonders wichtig, den TAF-Callback am Ende eines Requests zu deregistrieren, da die Verbindung im nächsten Request möglicherweise von einem anderen Prozess/Thread übernommen wird. Ein veralteter Callback könnte sonst unerwartetes Verhalten auslösen.

Verfügbarkeit: Die Funktion steht erst ab PHP 5.3.12 bzw. PHP 5.4.2 zur Verfügung (abhängig vom genauen Release-Branch). In älteren Versionen ist sie nicht vorhanden.

Siehe auch

oci_register_taf_callback oci_connect oci_pconnect oci_new_connect