pg_set_chunked_rows_size — Funktion · PHP-Referenz

Signatur

pg_set_chunked_rows_size(PgSql\Connection $connection, int $size): bool

Beschreibung

Mit pg_set_chunked_rows_size() wird die PostgreSQL-Verbindung so konfiguriert, dass nachfolgende Abfrageergebnisse nicht als vollständiges Resultset, sondern in Blöcken (Chunks) einer festgelegten Zeilenzahl abgerufen werden. Dies ist besonders bei sehr großen Ergebnismengen vorteilhaft, da nicht das gesamte Ergebnis auf einmal in den Speicher geladen werden muss.

Der Chunk-Modus wird intern durch den Einsatz von Cursor-Mechanismen in der libpq-Bibliothek realisiert. Nach dem Aktivieren werden Ergebnisse, die mit pg_get_result() oder ähnlichen Funktionen abgerufen werden, in Blöcken der angegebenen Größe geliefert, anstatt alle Zeilen auf einmal zu übertragen.

Diese Funktion eignet sich besonders für Batch-Verarbeitungen, ETL-Prozesse oder jede Situation, in der sehr viele Datensätze aus PostgreSQL gelesen werden müssen, ohne den Speicherverbrauch der Anwendung zu überlasten. Sie ist nur für asynchrone Abfragen gedacht und sollte zusammen mit pg_send_query() oder pg_send_query_params() verwendet werden.

Der Chunk-Modus gilt für alle nachfolgenden Abfragen auf dieser Verbindung, bis er durch Übergabe von 0 als size wieder deaktiviert wird.

Parameter

Name	Typ	Default	Beschreibung
$connection Pflicht	PgSql\Connection		Eine aktive PostgreSQL-Datenbankverbindung, wie sie von `pg_connect()` oder `pg_pconnect()` zurückgegeben wird.
$size Pflicht	int		Die Anzahl der Zeilen pro Chunk. Muss eine positive ganze Zahl sein. Bei Übergabe von `0` wird der Chunk-Modus deaktiviert und das Standardverhalten (vollständiges Resultset) wiederhergestellt.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Chunk-Modus erfolgreich gesetzt wurde, andernfalls false (z. B. bei einer ungültigen Verbindung oder einem ungültigen size-Wert).

Beispiele

Große Ergebnismenge speicherschonend in Chunks verarbeiten

<?php
$conn = pg_connect('host=localhost dbname=mydb user=myuser password=secret');
if (!$conn) {
    die('Verbindung fehlgeschlagen');
}

// Chunk-Modus aktivieren: jeweils 100 Zeilen pro Block
if (!pg_set_chunked_rows_size($conn, 100)) {
    die('Chunk-Modus konnte nicht aktiviert werden');
}

// Asynchrone Abfrage senden
if (!pg_send_query($conn, 'SELECT * FROM grosse_tabelle ORDER BY id')) {
    die('Abfrage konnte nicht gesendet werden');
}

// Ergebnisse chunk-weise abrufen
while ($result = pg_get_result($conn)) {
    if (pg_result_status($result) === PGSQL_FATAL_ERROR) {
        echo 'Fehler: ' . pg_result_error($result);
        break;
    }
    $numRows = pg_num_rows($result);
    echo "Chunk mit {$numRows} Zeile(n) empfangen.\n";
    for ($i = 0; $i < $numRows; $i++) {
        $row = pg_fetch_assoc($result, $i);
        // Zeilenverarbeitung hier
        // echo $row['id'] . "\n";
    }
    pg_free_result($result);
}

// Chunk-Modus wieder deaktivieren
pg_set_chunked_rows_size($conn, 0);
pg_close($conn);

Chunk mit 100 Zeile(n) empfangen. Chunk mit 100 Zeile(n) empfangen. Chunk mit 43 Zeile(n) empfangen.

Chunk-Modus mit parametrisierten Abfragen

<?php
$conn = pg_connect('host=localhost dbname=mydb user=myuser password=secret');
if (!$conn) {
    die('Verbindung fehlgeschlagen');
}

// Chunk-Größe auf 500 Zeilen setzen
pg_set_chunked_rows_size($conn, 500);

$minId = 1000;

// Parametrisierte asynchrone Abfrage
pg_send_query_params(
    $conn,
    'SELECT id, name, email FROM benutzer WHERE id &gt; $1',
    [$minId]
);

$totalRows = 0;
while ($result = pg_get_result($conn)) {
    $rows = pg_num_rows($result);
    $totalRows += $rows;
    echo "Verarbeite {$rows} Datensätze ...\n";
    pg_free_result($result);
}

echo "Gesamt verarbeitete Zeilen: {$totalRows}\n";

pg_close($conn);

Verarbeite 500 Datensätze ... Verarbeite 500 Datensätze ... Verarbeite 217 Datensätze ... Gesamt verarbeitete Zeilen: 1217

// Wichtig · Fallstricke

Nur für asynchrone Abfragen: Der Chunk-Modus funktioniert ausschließlich mit asynchronen Abfragefunktionen wie pg_send_query(), pg_send_query_params() oder pg_send_prepare()/pg_send_execute(). Bei synchronen Funktionen wie pg_query() hat er keine Wirkung.

Transaktionen: Intern verwendet libpq Cursor, um den Chunk-Modus zu implementieren. Dies setzt voraus, dass die Abfrage innerhalb einer Transaktion ausgeführt wird. PHP übernimmt dies automatisch, falls keine explizite Transaktion aktiv ist.

Speicherverbrauch: Obwohl der Chunk-Modus den Speicherverbrauch deutlich reduziert, verursacht er mehr Netzwerk-Roundtrips zur Datenbank. Der optimale Wert für size hängt von der Zeilengröße und den Netzwerkbedingungen ab.

PHP-Version: Diese Funktion ist erst ab PHP 8.4.0 verfügbar. In älteren Versionen muss der Chunk-basierte Abruf manuell über DECLARE CURSOR und FETCH in SQL implementiert werden.

Siehe auch

pg_connect pg_send_query pg_send_query_params pg_get_result pg_fetch_assoc pg_num_rows pg_free_result