Signatur
Beschreibung
oci_set_prefetch() steuert, wie viele Ergebniszeilen Oracle im Voraus vom Datenbankserver abruft und zwischenpuffert, bevor PHP sie einzeln über oci_fetch_*()-Funktionen anfordert. Ein höherer Prefetch-Wert senkt die Anzahl der Netzwerk-Roundtrips zwischen PHP und dem Oracle-Datenbankserver erheblich und kann die Performance bei großen Ergebnismengen deutlich steigern.
Die Funktion muss nach oci_parse() und vor oci_execute() aufgerufen werden. Der Standardwert für das Prefetching beträgt 100 Zeilen (ab Oracle-Client-Bibliothek 11.2) bzw. 1 Zeile bei älteren Versionen. Ein Wert von 0 deaktiviert das Prefetching vollständig.
Besonders sinnvoll ist ein erhöhter Prefetch-Wert, wenn große Tabellenmengen sequenziell verarbeitet werden und der Datenbankserver über ein Netzwerk erreichbar ist. Zu hohe Werte können jedoch den Speicherverbrauch auf dem PHP-Server erhöhen, da alle vorab geladenen Zeilen im Arbeitsspeicher gehalten werden.
Bei der Verwendung von REF CURSORs oder Array-Fetch mit oci_fetch_array() in Verbindung mit OCI_FETCHSTATEMENT_BY_ROW oder OCI_FETCHSTATEMENT_BY_COLUMN hat der Prefetch-Wert ebenfalls Einfluss auf die Performance und sollte entsprechend angepasst werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $statement Pflicht | resource | Ein gültiges OCI-Statement-Handle, wie es von oci_parse() zurückgegeben wird. |
|
| $rows Pflicht | int | Anzahl der vorab zu ladenden Zeilen. Muss >= 0 sein. Ein Wert von 0 deaktiviert das Prefetching. Negative Werte führen zu einem Fehler. |
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler (z. B. ungültiges Statement-Handle oder negativer Zeilenwert).Beispiele
Prefetch für eine einfache SELECT-Abfrage setzen
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlspecialchars($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$sql = 'SELECT employee_id, last_name FROM employees ORDER BY employee_id';
$stid = oci_parse($conn, $sql);
// 200 Zeilen auf einmal vorab laden
oci_set_prefetch($stid, 200);
oci_execute($stid);
while ($row = oci_fetch_array($stid, OCI_ASSOC + OCI_RETURN_NULLS)) {
echo $row['EMPLOYEE_ID'] . ': ' . $row['LAST_NAME'] . PHP_EOL;
}
oci_free_statement($stid);
oci_close($conn);Prefetch deaktivieren (Einzelzeilen-Modus)
<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
$e = oci_error();
trigger_error(htmlspecialchars($e['message'], ENT_QUOTES), E_USER_ERROR);
}
$sql = 'SELECT department_id, department_name FROM departments WHERE rownum <= 5';
$stid = oci_parse($conn, $sql);
// Prefetch vollständig deaktivieren — jede Zeile wird einzeln abgerufen
oci_set_prefetch($stid, 0);
oci_execute($stid);
while ($row = oci_fetch_assoc($stid)) {
echo $row['DEPARTMENT_ID'] . ': ' . $row['DEPARTMENT_NAME'] . PHP_EOL;
}
oci_free_statement($stid);
oci_close($conn);// Wichtig · Fallstricke
Timing: oci_set_prefetch() muss zwingend nach oci_parse() und vor oci_execute() aufgerufen werden. Ein Aufruf nach oci_execute() hat keine Wirkung.
Speicherverbrauch: Ein sehr hoher Prefetch-Wert (z. B. 10.000+) kann bei breiten Tabellen mit vielen Spalten oder großen Feldwerten zu erheblichem Speicherverbrauch auf dem PHP-Server führen. Den Wert daher an die tatsächliche Datenmenge und verfügbaren Arbeitsspeicher anpassen.
LOB-Spalten: Bei Abfragen, die LOB-Spalten (CLOB, BLOB) enthalten, wird das Prefetching intern oft automatisch auf 0 zurückgesetzt, da LOBs separat behandelt werden müssen.
php.ini-Alternative: Der globale Standardwert kann über die INI-Direktive oci8.default_prefetch in der php.ini festgelegt werden. oci_set_prefetch() überschreibt diesen Wert für das jeweilige Statement.