pg_insert — Funktion · PHP-Referenz

Signatur

pg_insert(PgSql\Connection $connection, string $table_name, array $values, int $flags = PGSQL_DML_EXEC): string|bool

Beschreibung

pg_insert() nimmt ein assoziatives Array, dessen Schlüssel Spaltennamen und dessen Werte die einzufügenden Daten sind, und erzeugt daraus automatisch eine INSERT INTO-Anweisung für die angegebene PostgreSQL-Tabelle. Die Funktion übernimmt dabei das korrekte Escaping der Werte, sodass SQL-Injection-Angriffe über die Datenwerte verhindert werden.

Das Verhalten der Funktion wird über den Parameter $flags gesteuert: Mit PGSQL_DML_EXEC (Standard) wird das Statement sofort ausgeführt, mit PGSQL_DML_STRING wird stattdessen der erzeugte SQL-String zurückgegeben, ohne ihn auszuführen. Das Flag PGSQL_DML_ASYNC sendet die Abfrage asynchron. Die Flags lassen sich kombinieren (Bit-OR).

Ein praktischer Einsatz von pg_insert() ist das schnelle Persistieren von Formulardaten oder API-Payloads, die bereits als assoziatives Array vorliegen, ohne manuell einen INSERT-SQL-String zusammenzubauen. Die Funktion prüft die Spaltennamen anhand der tatsächlichen Tabellen-Metadaten und weist unbekannte Spalten ab.

Zu beachten ist, dass pg_insert() nicht als vollständiger Ersatz für Prepared Statements mit pg_prepare() / pg_execute() gilt, wenn maximale Kontrolle und Wiederverwendbarkeit benötigt wird. Für einfache Einzel-Inserts ist sie jedoch komfortabel und sicher nutzbar.

Parameter

Name	Typ	Default	Beschreibung
$connection Pflicht	PgSql\Connection		Eine aktive PostgreSQL-Verbindungsinstanz, wie sie von `pg_connect()` oder `pg_pconnect()` zurückgegeben wird.
$table_name Pflicht	string		Name der Zieltabelle, in die die Daten eingefügt werden sollen. Der Name muss in der Datenbank vorhanden sein, da `pg_insert()` die Spaltennamen gegen die Tabellen-Metadaten validiert.
$values Pflicht	array		Assoziatives Array, bei dem die Schlüssel den Spaltennamen und die Werte den einzufügenden Datenwerten entsprechen. Unbekannte Spaltennamen führen zu einem Fehler.
$flags	int	PGSQL_DML_EXEC	Kombination aus Steuer-Flags: `PGSQL_DML_EXEC` (Abfrage ausführen), `PGSQL_DML_ASYNC` (asynchron ausführen), `PGSQL_DML_STRING` (SQL-String zurückgeben statt ausführen), `PGSQL_DML_ESCAPE` (Werte escapen). Mehrere Flags werden per Bit-OR kombiniert.

Rückgabewert

Typ

string|bool

Beschreibung

Gibt true zurück, wenn der INSERT erfolgreich ausgeführt wurde. Bei gesetztem Flag PGSQL_DML_STRING wird der erzeugte SQL-String zurückgegeben. Im Fehlerfall wird false zurückgegeben.

Beispiele

Einfaches Einfügen eines Datensatzes

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

$data = [
    'name'  => 'Max Mustermann',
    'email' => 'max@example.com',
    'age'   => 30,
];

$result = pg_insert($conn, 'customers', $data);

if ($result === true) {
    echo 'Datensatz erfolgreich eingefügt.';
} else {
    echo 'Fehler beim Einfügen.';
}

pg_close($conn);

Datensatz erfolgreich eingefügt.

SQL-String vorab prüfen (Dry-Run mit PGSQL_DML_STRING)

<?php
$conn = pg_connect('host=localhost dbname=shop user=app password=secret');

$data = [
    'product_name' => 'Laptop',
    'price'        => 999.99,
    'stock'        => 42,
];

// Nur den SQL-String erzeugen, nicht ausführen
$sql = pg_insert($conn, 'products', $data, PGSQL_DML_STRING | PGSQL_DML_ESCAPE);

echo $sql;

INSERT INTO "products" ("product_name","price","stock") VALUES ('Laptop','999.99','42')

// Wichtig · Fallstricke

Sicherheit: Obwohl pg_insert() die Werte des Arrays escapt, sollten die Schlüssel (Spaltennamen) niemals direkt aus Nutzereingaben stammen, da diese nicht auf dieselbe Weise geschützt werden. Filtere Spaltennamen stets anhand einer Whitelist erlaubter Felder.

Typkompatibilität: Die Funktion versucht, PHP-Typen automatisch in passende PostgreSQL-Typen zu konvertieren. Bei komplexen Typen (z. B. Arrays, JSON, hstore) kann es zu unerwartetem Verhalten kommen – hier empfiehlt sich der Einsatz von pg_query_params() mit expliziter Typangabe.

PHP 8.1: Ab PHP 8.1 ist der erste Parameter vom Typ PgSql\Connection (Objekt) statt der früheren Ressource.

Siehe auch

pg_connect pg_update pg_delete pg_select pg_query_params pg_prepare pg_execute