El soporte de la reanudación transparente de aplicación (TAF) de OCI8

master Ver versión oficial en línea Licencia CC-BY-3.0Descargado el 2026-08-02

En esta página

El soporte de la reanudación transparente de aplicación (TAF) de OCI8#
Configuración de la reanudación transparente de aplicación#
Uso de las funciones de retrollamada TAF en OCI8#
Véase también#

El soporte de la reanudación transparente de aplicación (TAF) de OCI8#

TAF es una funcionalidad de la base de datos Oracle que proporciona alta disponibilidad. Permite que las aplicaciones PHP OCI8 se reconecten automáticamente a una base de datos preconfigurada cuando la conectividad a la base de datos falla debido a una falla de instancia o de red.

En un sistema de base de datos Oracle configurado, TAF ocurre cuando la aplicación PHP detecta que la instancia de la base de datos está fuera de servicio o inalcanzable. Establece una conexión a otro nodo en una configuración Oracle RAC, una base de datos de respaldo en caliente, o la misma instancia de la base de datos ella misma. Consulte el Guía del programador de la interfaz de llamada Oracle para más información sobre OCI TAF.

Una función de retrollamada de aplicación puede ser registrada con oci_register_taf_callback. Durante la reanudación, el procesamiento normal de la aplicación se detiene y la retrollamada registrada es invocada. La función de retrollamada notifica a la aplicación de los eventos de reanudación. Si la reanudación tiene éxito, el procesamiento normal se reanudará. Si la reanudación es abandonada, todas las operaciones de base de datos siguientes en la aplicación fallarán debido a la falta de una conexión disponible.

Cuando la conexión falla en otra base de datos, la función de retrollamada puede restablecer cualquier estado de conexión necesario, por ejemplo, rejugando los comandos ALTER SESSION necesarios si el servicio de base de datos no tenía -failover_restore activado.

Una función de retrollamada de aplicación puede ser eliminada llamando a oci_unregister_taf_callback.

Configuración de la reanudación transparente de aplicación#

TAF puede ser configurado del lado PHP OCI8 o en la configuración de la base de datos. Si ambos están configurados, los parámetros del lado de la base de datos tienen prioridad.

Configurar TAF en PHP OCI8 (el lado cliente) incluyendo el parámetro FAILOVER_MODE en la parte CONNECT_DATA de un descriptor de conexión. Consulte la sección Configuración de la reanudación transparente de aplicación del Guía del administrador de Oracle Database Net Services para más información sobre la configuración del lado cliente de TAF.

Un ejemplo de tnsnames.ora para configurar TAF reconectando a la misma instancia de la base de datos:

    ORCL =
      (DESCRIPTION =
        (ADDRESS = (PROTOCOL = TCP)(HOST = 127.0.0.1)(PORT = 1521))
        (CONNECT_DATA =
          (SERVICE_NAME = orclpdb1)
          (FAILOVER_MODE =
            (TYPE = SELECT)
            (METHOD = BASIC)
            (RETRIES = 20)
            (DELAY = 15))))

También es posible configurar TAF del lado de la base de datos modificando el servicio objetivo con srvctl (para RAC) o la procedimiento empaquetado DBMS_SERVICE.MODIFY_SERVICE (para bases de datos de instancia única).

Uso de las funciones de retrollamada TAF en OCI8#

Una función de retrollamada TAF es una función de aplicación que puede ser registrada para ser llamada durante la reanudación. Es llamada varias veces durante la reanudación de la conexión de la aplicación.

La función de retrollamada es llamada por primera vez cuando se detecta una pérdida de conexión. Esto permite que la aplicación actúe en consecuencia para los retrasos venideros de la reanudación. Si la reanudación tiene éxito, la función de retrollamada es invocada después de que la conexión sea restablecida y utilizable. En ese momento, la aplicación puede resincronizar los parámetros de sesión y tomar acciones tales como informar al usuario que una reanudación ha ocurrido. Si la reanudación es infructuosa, una retrollamada ocurre para informar a la aplicación que una reanudación no ha ocurrido y que la conexión no es utilizable.

La interfaz de una función de retrollamada TAF definida por el usuario es la siguiente:

userCallbackFn(resource $connection, int $event, int $type): int
```php

`connection`  
La conexión Oracle en la que la retrollamada TAF ha sido registrada vía `oci_register_taf_callback`. La conexión no es válida hasta que la reanudación no termine con éxito.

`event`  
El evento de reanudación indica el estado actual de la reanudación.

- `OCI_FO_BEGIN` indica que la reanudación ha detectado una pérdida de conexión y que la reanudación comienza.

- `OCI_FO_END` indica que la reanudación ha tenido éxito.

- `OCI_FO_ABORT` indica que la reanudación ha fallado y que no hay opción de reintentar.

- `OCI_FO_ERROR` indica asimismo que la reanudación ha fallado, pero da a la aplicación la oportunidad de manejar el error y devolver OCI_FO_RETRY para reintentar la reanudación.

- `OCI_FO_REAUTH` indica que un usuario Oracle ha sido reautenticado.

`type`  
El tipo de reanudación. Esto permite a la retrollamada saber qué tipo de reanudación la aplicación ha solicitado. Los valores habituales son los siguientes:

- `OCI_FO_SESSION` indica que el usuario ha solicitado únicamente la reanudación de sesión. Por ejemplo, si la conexión de un usuario se pierde, una nueva sesión es automáticamente creada para el usuario en la base de datos de respaldo. Este tipo de reanudación no intenta recuperar los SELECT.

- `OCI_FO_SELECT` indica que el usuario ha solicitado la reanudación SELECT asimismo. Permite a los usuarios con cursores abiertos continuar recuperándolos después de una falla.

`valor de retorno`  
- `0` indica que los pasos de reanudación deben continuar normalmente.

- `OCI_FO_RETRY` indica que la reanudación debe ser intentada nuevamente por Oracle. En caso de error al reanudar a una nueva conexión, TAF es capaz de reintentar la reanudación. En general, el código de la aplicación debe dormir durante un cierto tiempo antes de devolver OCI_FO_RETRY.

Registro de una función de retrollamada TAF

= 20) return 0; printf(" Error de reanudación recibido. Durmiendo...\n"); sleep(10); self::$retry_count++; return OCI_FO_RETRY; // reintentar reanudación break; default: printf("Evento de reanudación incorrecto: %d.\n", $event); break; } return 0; } } $fn_name = 'MyClass::TAFCallback'; $conn = oci_connect('hr', 'welcome', 'orcl'); $sysconn = oci_connect('system', 'oracle', 'orcl'); // Usar una conexión privilegiada para construir una instrucción SQL que iniciará la reanudación $sql = <<< 'END' select unique 'alter system disconnect session '''||sid||','||serial#||'''' from v$session_connect_info where sid = sys_context('USERENV', 'SID') END; $s = oci_parse($conn, $sql); oci_execute($s); $r = oci_fetch_array($s); $disconnectssql = $r[0]; oci_register_taf_callback($conn, $fn_name); // Registrar TAFCallback a Oracle TAF print "Analizando consulta de usuario\n"; $sql = "select systimestamp from dual"; $stmt = oci_parse($conn, $sql); // Por ejemplo, si una pérdida de conexión ocurre en este momento, oci_execute() detectará // la pérdida y la reanudación comenzará. Durante la reanudación, oci_execute() invocará // la función de retrollamada TAF varias veces. Si la reanudación tiene éxito, // una nueva conexión es creada de manera transparente y oci_execute() continuará como // de costumbre. Los parámetros de sesión de la conexión pueden ser restablecidos en la función de retrollamada TAF. // Si la reanudación es abandonada, oci_execute() devolverá un error // ya que una conexión válida no está disponible. // Desconectar al usuario, lo que inicia la reanudación print "Desconectando al usuario\n"; $discsql = oci_parse($sysconn, $disconnectssql); oci_execute($discsql); print "Ejecutando consulta de usuario\n"; $e = oci_execute($stmt); if (!$e) { $m = oci_error($stmt); trigger_error("No se pudo ejecutar la sentencia: ". $m['message'], E_USER_ERROR); } $row = oci_fetch_array($stmt); print $row[0] . "\n"; // hacer otras instrucciones SQL con la nueva conexión, si es válida // $stmt = oci_parse($conn, . . .); ?>

```php

Véase también#

oci_register_taf_callback

oci_unregister_taf_callback