pg_copy_to — Funktion · PHP-Referenz

Signatur

pg_copy_to(PgSql\Connection $connection, string $table_name, string $separator = "\t", string $null_as = "\\N"): array|false

Beschreibung

pg_copy_to() nutzt den PostgreSQL-Befehl COPY <table> TO STDOUT, um alle Zeilen einer Tabelle effizient in ein PHP-Array zu übertragen. Jedes Element des zurückgegebenen Arrays entspricht einer Zeile der Tabelle im Text- oder CSV-Format, inklusive eines abschließenden Zeilenumbruchs (\n).

Die Funktion ist besonders nützlich für schnelle Daten-Exporte oder Backups einzelner Tabellen, da der COPY-Mechanismus von PostgreSQL deutlich schneller ist als ein zeilenweises SELECT mit anschließendem Iterieren. Das Ergebnis-Array lässt sich direkt an pg_copy_from() übergeben, um die Daten in eine andere Tabelle oder Datenbank zu importieren.

Der Parameter separator legt das Trennzeichen zwischen den Spalten fest (Standard: Tabulator). Mit null_as wird kontrolliert, wie NULL-Werte im Ausgabeformat dargestellt werden. Beide Parameter müssen mit den Einstellungen übereinstimmen, die beim späteren Import mit pg_copy_from() verwendet werden.

Zu beachten ist, dass pg_copy_to() stets die gesamte Tabelle exportiert. Für selektive Exporte muss die Tabelle durch eine View oder eine benannte Abfrage ersetzt werden — direkte SQL-Filterung ist nicht möglich.

Parameter

Name	Typ	Default	Beschreibung
$connection Pflicht	PgSql\Connection		Eine aktive PostgreSQL-Datenbankverbindung, wie sie von `pg_connect()` oder `pg_pconnect()` zurückgegeben wird.
$table_name Pflicht	string		Name der Tabelle, deren Inhalt exportiert werden soll. Es kann auch eine SQL-Abfrage in der Form `COPY (SELECT ...) TO STDOUT` angegeben werden, sofern der PostgreSQL-Server dies unterstützt — in diesem Fall den gesamten `COPY`-Befehl als String übergeben.
$separator	string	\t	Das Trennzeichen zwischen den Spalten einer Zeile. Standard ist der Tabulator (`\t`). Muss mit dem beim Import verwendeten Trennzeichen übereinstimmen.
$null_as	string	\\N	Zeichenkette, durch die `NULL`-Werte in der Ausgabe repräsentiert werden. Standard ist `\\N` (Backslash gefolgt von N). Muss beim Import gleich gesetzt sein.

Rückgabewert

Typ

array|false

Beschreibung

Gibt ein Array von Strings zurück, wobei jedes Element einer Tabellenzeile entspricht (mit abschließendem \n). Im Fehlerfall wird false zurückgegeben.

Beispiele

Tabelle in Array exportieren und ausgeben

<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=geheim');
if (!$conn) {
    die('Verbindung fehlgeschlagen');
}

// Gesamten Inhalt der Tabelle 'produkte' exportieren
$rows = pg_copy_to($conn, 'produkte');

if ($rows === false) {
    die('Export fehlgeschlagen');
}

// Jede Zeile ausgeben
foreach ($rows as $row) {
    echo $row; // enthält bereits \n am Ende
}

pg_close($conn);

1 Laptop 999.99 2 Maus 19.99 3 Tastatur 49.99

Tabelle kopieren: Export und Import in eine andere Tabelle

<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=geheim');
if (!$conn) {
    die('Verbindung fehlgeschlagen');
}

// Daten aus Quelltabelle exportieren (mit Semikolon als Trennzeichen)
$data = pg_copy_to($conn, 'produkte', ';', 'NULL');

if ($data === false) {
    die('Export fehlgeschlagen');
}

echo 'Exportierte Zeilen: ' . count($data) . PHP_EOL;

// Daten in Zieltabelle importieren (gleiche Separator/Null-Einstellungen!)
$result = pg_copy_from($conn, 'produkte_backup', $data, ';', 'NULL');

if ($result) {
    echo 'Import erfolgreich.';
} else {
    echo 'Import fehlgeschlagen.';
}

pg_close($conn);

Exportierte Zeilen: 3 Import erfolgreich.

// Wichtig · Fallstricke

Sicherheit: Der Parameter table_name sollte niemals direkt aus Benutzereingaben übernommen werden, da er nicht automatisch escaped wird. Verwende stets validierte oder fest kodierte Tabellennamen, um SQL-Injection zu verhindern.

Performance: Der COPY-Mechanismus ist für große Datenmengen deutlich schneller als zeilenweise SELECT-Abfragen, kann aber bei sehr großen Tabellen zu hohem Speicherverbrauch führen, da alle Daten in ein PHP-Array geladen werden.

PostgreSQL-Berechtigungen: Für die Ausführung von COPY TO STDOUT benötigt der Datenbankbenutzer SELECT-Rechte auf die betreffende Tabelle. Das server-seitige COPY TO <Datei> erfordert Superuser-Rechte, wird von dieser Funktion aber nicht verwendet.

Ab PHP 8.1 ist der Rückgabewert von pg_connect() eine Instanz von PgSql\Connection statt einer Ressource. Die Funktion bleibt aber abwärtskompatibel.

Siehe auch

pg_copy_from pg_connect pg_query pg_fetch_all