Signatur
Beschreibung
oci_pconnect() öffnet eine persistente Verbindung zur Oracle-Datenbank. Im Gegensatz zu oci_connect() wird die Verbindung nach dem Ende des PHP-Skripts nicht geschlossen, sondern im Verbindungspool des Webservers (z. B. Apache) gehalten und beim nächsten Aufruf mit denselben Parametern wiederverwendet. Dies reduziert den Overhead durch wiederholtes Aufbauen von Datenbankverbindungen erheblich.
Wenn eine bereits vorhandene persistente Verbindung mit identischem Benutzernamen, Passwort, Verbindungsstring und Zeichensatz existiert, wird diese zurückgegeben, ohne eine neue Verbindung zu Oracle zu öffnen. Dadurch eignet sich die Funktion besonders für Hochlast-Webanwendungen, bei denen viele kurze Anfragen auf dieselbe Datenbank zugreifen.
Wichtig ist zu beachten, dass bei persistenten Verbindungen der Verbindungsstatus zwischen Requests geteilt werden kann. Offene Transaktionen oder geänderte Session-Parameter aus einem vorherigen Request können noch aktiv sein. Es empfiehlt sich daher, den Sitzungsstatus explizit zurückzusetzen (z. B. mit ROLLBACK) oder Session-Parameter neu zu setzen.
Für den Verbindungsstring kann der Oracle Net-Alias aus der tnsnames.ora, eine Easy Connect-Zeichenkette (Host/Port/Servicename) oder ein vollständiger TNS-Verbindungsdeskriptor verwendet werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $username Pflicht | string | Der Oracle-Datenbankbenutzername für die Anmeldung. | |
| $password Pflicht | string | Das Passwort des Oracle-Datenbankbenutzers. | |
| $connection_string | string | Der Oracle-Verbindungsstring, z. B. ein TNS-Alias aus der tnsnames.ora, eine Easy Connect-Zeichenkette wie host:port/servicename oder ein vollständiger TNS-Deskriptor. Wird kein Wert angegeben, wird die Umgebungsvariable ORACLE_SID verwendet. |
|
| $encoding | string | Der Zeichensatz für die Verbindung (Oracle NLS_LANG-Wert), z. B. AL32UTF8. Wird er nicht angegeben, wird der Standardzeichensatz der Oracle-Client-Bibliothek verwendet. |
|
| $session_mode | int | OCI_DEFAULT | Verbindungsmodus. Mögliche Werte: OCI_DEFAULT, OCI_SYSOPER, OCI_SYSDBA (erfordern Berechtigungen). Ab PHP 5.3 auch OCI_CRED_EXT für externe Authentifizierung. |
Rückgabewert
false zurückgegeben; Details können mit oci_error() abgefragt werden.Beispiele
Einfache persistente Verbindung via Easy Connect
<?php
$conn = oci_pconnect('hr', 'geheim', 'localhost:1521/XEPDB1', 'AL32UTF8');
if (!$conn) {
$e = oci_error();
trigger_error('Verbindung fehlgeschlagen: ' . htmlspecialchars($e['message']), E_USER_ERROR);
}
$stid = oci_parse($conn, 'SELECT SYSDATE FROM DUAL');
oci_execute($stid);
while ($row = oci_fetch_array($stid, OCI_ASSOC)) {
echo 'Aktuelles Datum: ' . $row['SYSDATE'] . PHP_EOL;
}
oci_free_statement($stid);
// Verbindung bleibt persistent – kein oci_close() nötig, aber möglich
Persistente Verbindung mit Rollback zur Sicherheit
<?php
$conn = oci_pconnect('app_user', 'app_pass', 'db.example.com:1521/PROD');
if (!$conn) {
$e = oci_error();
throw new RuntimeException('Oracle-Verbindung fehlgeschlagen: ' . $e['message']);
}
// Sicherheitshalber offene Transaktionen aus vorherigen Requests zurückrollen
$rollback = oci_parse($conn, 'ROLLBACK');
oci_execute($rollback);
oci_free_statement($rollback);
// Eigentliche Abfrage
$stmt = oci_parse($conn, 'SELECT employee_id, last_name FROM employees WHERE rownum <= 5');
oci_execute($stmt);
while ($row = oci_fetch_array($stmt, OCI_ASSOC + OCI_RETURN_NULLS)) {
printf("ID: %d | Name: %s\n", $row['EMPLOYEE_ID'], $row['LAST_NAME']);
}
oci_free_statement($stmt);
// Wichtig · Fallstricke
Transaktionsstatus: Bei persistenten Verbindungen kann ein vorangegangener Request eine nicht abgeschlossene Transaktion hinterlassen haben. Es ist daher empfehlenswert, zu Beginn jedes Requests ein explizites ROLLBACK auszuführen oder sicherzustellen, dass alle Transaktionen korrekt abgeschlossen werden.
Session-Parameter: Oracle-Session-Einstellungen wie NLS_DATE_FORMAT oder TIME_ZONE können über persistente Verbindungen hinweg bestehen bleiben. Setze solche Parameter am Anfang des Requests explizit, wenn du definiertes Verhalten benötigst.
Sicherheit: Benutzername und Passwort sollten niemals im Quellcode hartcodiert werden. Nutze Umgebungsvariablen oder eine sichere Konfigurationsdatei, die außerhalb des Webroot liegt.
Verbindungsanzahl: Zu viele persistente Verbindungen können Oracle-seitige Ressourcenlimits (Prozesse/Sessions) überschreiten. Achte auf die Einstellungen in init.ora bzw. pfile und dimensioniere den Apache-Prozesspool entsprechend.