pg_copy_from — Funktion · PHP-Referenz

Signatur

pg_copy_from(PgSql\Connection $connection, string $table_name, array $rows, string $separator = "\t", string $null_as = "\\N"): bool

Beschreibung

pg_copy_from() nutzt den PostgreSQL-internen COPY FROM STDIN-Befehl, um eine Liste von Zeilen aus einem PHP-Array schnell in eine Datenbanktabelle zu schreiben. Jedes Element des Arrays repräsentiert dabei eine einzelne Zeile, deren Felder standardmäßig durch Tabulatoren (\t) getrennt sind. Diese Methode ist erheblich performanter als das Ausführen vieler einzelner INSERT-Statements, besonders bei großen Datenmengen.

Der Parameter separator legt das Trennzeichen zwischen den Spalten fest; null_as bestimmt, wie NULL-Werte in den Rohdaten repräsentiert werden (standardmäßig als der Literal-String \N, wie von PostgreSQL erwartet). Alle Zeilen im Array müssen entsprechend formatiert sein.

Die Funktion wird typischerweise zusammen mit pg_copy_to() verwendet, um Daten zwischen Tabellen oder Datenbanken zu übertragen. Sie eignet sich ideal für Bulk-Importe, ETL-Prozesse oder das Wiederherstellen von Tabellen-Snapshots.

Achtung: Die Eingabedaten müssen korrekt formatiert und ggf. escapet sein, da die Daten direkt an PostgreSQL übergeben werden. Falsch formatierte Zeilen führen zu einem Fehler, der die gesamte Operation abbricht.

Parameter

Name	Typ	Default	Beschreibung
$connection Pflicht	PgSql\Connection		Eine aktive PostgreSQL-Datenbankverbindung, die zuvor mit `pg_connect()` oder `pg_pconnect()` erstellt wurde.
$table_name Pflicht	string		Name der Zieltabelle, in die die Daten eingefügt werden sollen. Optional kann eine Spaltenliste angegeben werden, z. B. `'meine_tabelle (spalte1, spalte2)'`.
$rows Pflicht	array		Ein numerisch indiziertes Array, bei dem jedes Element eine Zeile als String enthält. Die Felder innerhalb einer Zeile müssen durch das unter `separator` angegebene Zeichen getrennt sein.
$separator	string	\t	Das Trennzeichen, das die einzelnen Spaltenfelder innerhalb einer Zeile voneinander trennt. Standard ist der Tabulator (`\t`).
$null_as	string	\\N	Die Zeichenkette, die in den Rohdaten als Repräsentation für `NULL` verwendet wird. Standard ist `\N` (der PostgreSQL-Standard für COPY-Operationen).

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn alle Zeilen erfolgreich eingefügt wurden. Bei einem Fehler (z. B. falsch formatierte Daten, Schemakonflikte) wird false zurückgegeben.

Beispiele

Einfacher Bulk-Import mit pg_copy_from

<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=geheim');

if (!$conn) {
    die('Verbindung fehlgeschlagen');
}

// Zeilen im Tab-getrennten Format vorbereiten
$rows = [
    "1\tAlice\talice@example.com",
    "2\tBob\tbob@example.com",
    "3\tCarol\tcarol@example.com",
];

$result = pg_copy_from($conn, 'benutzer', $rows);

if ($result) {
    echo "Datensätze erfolgreich eingefügt.\n";
} else {
    echo "Fehler beim Einfügen der Datensätze.\n";
}

pg_close($conn);

Datensätze erfolgreich eingefügt.

Kombination von pg_copy_to und pg_copy_from zum Tabellenklonen

<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=geheim');

if (!$conn) {
    die('Verbindung fehlgeschlagen');
}

// Daten aus Quelltabelle lesen
$rows = pg_copy_to($conn, 'benutzer_alt');

if ($rows === false) {
    die('Fehler beim Lesen der Quelltabelle.');
}

// Daten in Zieltabelle schreiben
$result = pg_copy_from($conn, 'benutzer_neu', $rows);

if ($result) {
    echo "Tabelle erfolgreich geklont. " . count($rows) . " Zeilen kopiert.\n";
} else {
    echo "Fehler beim Einfügen in die Zieltabelle.\n";
}

pg_close($conn);

Tabelle erfolgreich geklont. 3 Zeilen kopiert.

Verwendung eines eigenen Trennzeichens und NULL-Repräsentation

<?php
$conn = pg_connect('host=localhost dbname=testdb user=postgres password=geheim');

// Semikolon als Trennzeichen, 'NULL' als NULL-Darstellung
$rows = [
    "10;Max Mustermann;NULL",
    "11;Erika Musterfrau;erika@example.com",
];

$result = pg_copy_from($conn, 'kontakte (id, name, email)', $rows, ';', 'NULL');

if ($result) {
    echo "Import erfolgreich.\n";
} else {
    echo "Import fehlgeschlagen.\n";
}

pg_close($conn);

Import erfolgreich.

// Wichtig · Fallstricke

Datensicherheit: Da die Daten direkt via COPY FROM STDIN an PostgreSQL übergeben werden, greifen die üblichen Mechanismen zur Parameterbindung (pg_query_params()) hier nicht. Eingaben aus nicht vertrauenswürdigen Quellen müssen vor der Übergabe an pg_copy_from() manuell validiert und ggf. escapet werden, um Datenkorruption oder unerwünschte Effekte zu verhindern.

Transaktionen: Schlägt die Operation fehl, werden keine Teilzeilen eingefügt — PostgreSQL bricht den gesamten COPY-Vorgang bei einem Fehler ab. Es empfiehlt sich, die Operation innerhalb einer expliziten Transaktion auszuführen, um den Datenbankzustand konsistent zu halten.

Zeilenformat: Jede Zeile im Array muss exakt so viele Felder enthalten, wie die Zieltabelle (bzw. die angegebene Spaltenliste) erwartet. Fehlende oder überzählige Felder führen zu einem PostgreSQL-Fehler. Zeilenumbrüche am Ende jedes Array-Elements (wie sie pg_copy_to() erzeugt) werden von pg_copy_from() korrekt verarbeitet.

Ab PHP 8.1 ist der Verbindungstyp PgSql\Connection; in älteren Versionen war es eine Ressource vom Typ resource.

Siehe auch

pg_copy_to pg_connect pg_query pg_query_params pg_insert