pg_lo_create — Funktion · PHP-Referenz

Signatur

pg_lo_create(PgSql\Connection $connection = ?, int $object_id = ?): int|false

Beschreibung

pg_lo_create() legt ein neues Large Object (LOB) in der aktuell verbundenen PostgreSQL-Datenbank an. Large Objects ermöglichen es, binäre Daten (z. B. Bilder, Dokumente oder andere Dateien) direkt in der Datenbank zu speichern, ohne sie in reguläre Tabellenfelder schreiben zu müssen. Das erzeugte Objekt wird durch eine eindeutige OID (Object Identifier) identifiziert.

Die Funktion gibt bei Erfolg eine ganzzahlige OID zurück, über die das Large Object mit anderen Funktionen wie pg_lo_open(), pg_lo_write(), pg_lo_read() und pg_lo_unlink() verwaltet werden kann. Der optionale Parameter $object_id erlaubt es, eine gewünschte OID explizit vorzugeben; wird er weggelassen, vergibt PostgreSQL automatisch eine freie OID.

Wichtig: Alle Operationen auf Large Objects müssen innerhalb einer Transaktion stattfinden. Ohne eine aktive Transaktion schlägt die Funktion fehl oder liefert unerwartete Ergebnisse. Daher sollte vor dem Aufruf stets pg_query($conn, 'BEGIN') ausgeführt werden.

Der Einsatz von Large Objects bietet gegenüber bytea-Feldern den Vorteil, dass sehr große Datenmengen (bis zu 4 TB) gespeichert und gezielt per Seek-Zeiger gelesen/geschrieben werden können, ohne die gesamte Datei auf einmal laden zu müssen.

Parameter

Name	Typ	Default	Beschreibung
$connection	PgSql\Connection		Eine aktive PostgreSQL-Datenbankverbindung, die mit `pg_connect()` oder `pg_pconnect()` erzeugt wurde. Wird dieser Parameter weggelassen, wird die zuletzt geöffnete Verbindung verwendet.
$object_id	int		Eine optionale, benutzerdefinierte OID für das neue Large Object. Ist die angegebene OID bereits vergeben, schlägt die Funktion fehl. Wird dieser Parameter nicht angegeben, weist PostgreSQL automatisch eine freie OID zu.

Rückgabewert

Typ

int|false

Beschreibung

Gibt bei Erfolg die OID des neu erzeugten Large Objects als int zurück. Im Fehlerfall (z. B. keine aktive Transaktion, ungültige Verbindung oder bereits belegte OID) wird false zurückgegeben.

Beispiele

Neues Large Object erstellen und Daten hineinschreiben

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

// Transaktion starten — zwingend erforderlich für Large Objects!
pg_query($conn, 'BEGIN');

// Neues Large Object erzeugen
$oid = pg_lo_create($conn);
if ($oid === false) {
    pg_query($conn, 'ROLLBACK');
    die('Large Object konnte nicht erstellt werden');
}

echo "Erzeugtes Large Object mit OID: $oid\n";

// Large Object öffnen und Daten schreiben
$lob = pg_lo_open($conn, $oid, 'w');
if ($lob === false) {
    pg_query($conn, 'ROLLBACK');
    die('Large Object konnte nicht geöffnet werden');
}

$data = 'Dies sind die gespeicherten Binärdaten des Large Objects.';
pg_lo_write($lob, $data);
pg_lo_close($lob);

pg_query($conn, 'COMMIT');
echo "Daten erfolgreich gespeichert.\n";
pg_close($conn);

Erzeugtes Large Object mit OID: 16398 Daten erfolgreich gespeichert.

Large Object mit benutzerdefinierter OID anlegen

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

pg_query($conn, 'BEGIN');

$gewuenschteOid = 99999;
$oid = pg_lo_create($conn, $gewuenschteOid);

if ($oid === false) {
    pg_query($conn, 'ROLLBACK');
    echo "Fehler: OID $gewuenschteOid ist möglicherweise bereits vergeben.\n";
} else {
    pg_query($conn, 'COMMIT');
    echo "Large Object mit gewünschter OID $oid erfolgreich erstellt.\n";
}

pg_close($conn);

Large Object mit gewünschter OID 99999 erfolgreich erstellt.

// Wichtig · Fallstricke

Transaktion zwingend erforderlich: PostgreSQL verlangt für alle Large-Object-Operationen eine aktive Transaktion. Ohne vorheriges pg_query($conn, 'BEGIN') schlägt pg_lo_create() fehl oder verhält sich undefiniert. Stellen Sie immer sicher, dass bei Fehler ein ROLLBACK durchgeführt wird.

Aufräumen nicht vergessen: Nicht mehr benötigte Large Objects müssen explizit mit pg_lo_unlink() gelöscht werden, da sie andernfalls dauerhaft in der Datenbank verbleiben und Speicherplatz verbrauchen, auch wenn keine Tabellenzeile mehr auf sie verweist.

Ressourcen-Typen ab PHP 8.1: Ab PHP 8.1 werden PostgreSQL-Verbindungen als PgSql\Connection-Objekte statt als resource-Handles zurückgegeben. Der Code sollte entsprechend angepasst werden.

Sicherheit: OIDs von Large Objects sollten niemals ungeprüft aus Benutzereingaben übernommen werden, da ein Angreifer damit gezielt auf vorhandene Large Objects zugreifen könnte.

Siehe auch

pg_lo_open pg_lo_close pg_lo_write pg_lo_read pg_lo_unlink pg_lo_import pg_lo_export pg_connect