pg_lo_import — Funktion · PHP-Referenz

Signatur

pg_lo_import(PgSql\Connection $connection, string $pathname, mixed $object_id = null): int|false

Beschreibung

pg_lo_import() liest eine lokale Datei vom Dateisystem des PHP-Servers und speichert deren Inhalt als PostgreSQL Large Object in der Datenbank. Als Rückgabewert liefert die Funktion die OID (Object Identifier) des neu angelegten Large Object, über die es später mit Funktionen wie pg_lo_open(), pg_lo_read() oder pg_lo_export() wieder abgerufen werden kann.

Large Objects eignen sich besonders zur Speicherung binärer Daten wie Bilder, PDFs oder andere große Dateien direkt in PostgreSQL, wenn eine Ablage im Dateisystem nicht gewünscht oder möglich ist. Im Gegensatz zu bytea-Spalten erlaubt die Large-Object-API gezielten wahlfreien Zugriff (Seek) auf Teile des Inhalts.

Der optionale Parameter object_id ermöglicht es, eine gewünschte OID explizit vorzugeben. PostgreSQL versucht dann, das Large Object unter dieser OID anzulegen. Diese Möglichkeit existiert ab PostgreSQL 8.1; bei älteren Versionen wird der Parameter ignoriert.

Wichtig: pg_lo_import() muss innerhalb einer Transaktion aufgerufen werden, da PostgreSQL Large-Object-Operationen transaktionsgebunden sind. Ein Aufruf außerhalb einer offenen Transaktion kann zu inkonsistenten Zuständen führen.

Parameter

Name	Typ	Default	Beschreibung
$connection Pflicht	PgSql\Connection		Eine aktive PostgreSQL-Datenbankverbindung, wie sie von `pg_connect()` oder `pg_pconnect()` zurückgegeben wird.
$pathname Pflicht	string		Vollständiger oder relativer Pfad zur Datei auf dem PHP-Server-Dateisystem, die als Large Object importiert werden soll.
$object_id	mixed	null	Optionale gewünschte OID für das neue Large Object. Wenn angegeben, versucht PostgreSQL (ab Version 8.1), das Objekt unter dieser OID zu registrieren. Wird `null` übergeben oder der Parameter weggelassen, vergibt PostgreSQL automatisch eine neue OID.

Rückgabewert

Typ

int|false

Beschreibung

Gibt die OID des neu erstellten Large Object als int zurück. Im Fehlerfall (z. B. Datei nicht vorhanden, keine offene Transaktion oder Datenbankfehler) wird false zurückgegeben.

Beispiele

Datei als Large Object importieren und OID speichern

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

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

$dateipfad = '/var/uploads/dokument.pdf';
$oid = pg_lo_import($conn, $dateipfad);

if ($oid === false) {
    pg_query($conn, 'ROLLBACK');
    die('Import fehlgeschlagen: ' . pg_last_error($conn));
}

// OID in einer Tabelle speichern, um das Large Object später zu referenzieren
pg_query($conn, "INSERT INTO dokumente (dateiname, lo_oid) VALUES ('dokument.pdf', $oid)");

pg_query($conn, 'COMMIT');
echo "Large Object erfolgreich importiert. OID: $oid\n";

pg_close($conn);
?>

Large Object erfolgreich importiert. OID: 24601

Import mit vorgegebener OID

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

pg_query($conn, 'BEGIN');

$gewuenschteOid = 99999;
$dateipfad = '/var/uploads/bild.png';
$oid = pg_lo_import($conn, $dateipfad, $gewuenschteOid);

if ($oid === false) {
    pg_query($conn, 'ROLLBACK');
    die('Import mit fester OID fehlgeschlagen: ' . pg_last_error($conn));
}

pg_query($conn, 'COMMIT');
echo "Large Object importiert unter OID: $oid\n";

pg_close($conn);
?>

Large Object importiert unter OID: 99999

// Wichtig · Fallstricke

Transaktion erforderlich: PostgreSQL Large-Object-Operationen sind zwingend an eine offene Transaktion gebunden. Ein Aufruf von pg_lo_import() ohne vorheriges BEGIN führt zu einem Fehler oder undefiniertem Verhalten.

Dateizugriff: Die importierte Datei wird vom PHP-Prozess gelesen. Der PHP-Serverprozess muss daher Lesezugriff auf die angegebene Datei besitzen. Bei Dateien aus Nutzer-Uploads sollte der Pfad sorgfältig validiert werden, um Path-Traversal-Angriffe (../) zu verhindern.

Speicherverbrauch: Sehr große Dateien können erheblichen Arbeitsspeicher beanspruchen, da die Datei vollständig geladen wird. Für sehr große Binärdaten sollte alternativ pg_lo_open() in Kombination mit pg_lo_write() und Streaming genutzt werden.

Aufräumen: Nicht mehr benötigte Large Objects müssen explizit mit pg_lo_unlink() gelöscht werden, da sie sonst dauerhaft in der Datenbank verbleiben und Speicher belegen.

Siehe auch

pg_lo_export pg_lo_open pg_lo_read pg_lo_write pg_lo_unlink pg_lo_create pg_connect