pg_lo_export — Funktion · PHP-Referenz

Signatur

pg_lo_export(PgSql\Connection $connection, int $oid, string $pathname): bool

Beschreibung

pg_lo_export() liest ein Large Object aus einer PostgreSQL-Datenbank und schreibt dessen Inhalt in eine Datei auf dem Dateisystem des Datenbankservers. Das Large Object wird über seine OID (Object Identifier) referenziert. Die Funktion ist das Gegenstück zu pg_lo_import().

Large Objects in PostgreSQL sind ein Mechanismus zum Speichern binärer Daten (z. B. Bilder, PDFs oder andere Dateien) in der Datenbank. Sie werden intern mit einem Typ oid referenziert. pg_lo_export() ist besonders nützlich, wenn man ein gespeichertes Objekt ohne zusätzlichen PHP-Puffer direkt auf den Datenbankserver-Disk schreiben möchte.

Der Aufruf muss innerhalb einer Transaktion erfolgen, da PostgreSQL Large-Object-Operationen nur innerhalb von Transaktionen erlaubt. Starte daher vorher pg_query($conn, 'BEGIN') und beende die Transaktion mit COMMIT oder ROLLBACK.

Zu beachten ist, dass der angegebene Dateipfad relativ zum Datenbankserver gilt – nicht zum Webserver oder PHP-Prozess. Wenn Datenbankserver und Webserver auf derselben Maschine laufen, ist das oft identisch, aber in verteilten Szenarien muss dies berücksichtigt werden.

Parameter

Name	Typ	Beschreibung
$connection Pflicht	PgSql\Connection	Eine gültige PostgreSQL-Datenbankverbindung, wie sie von `pg_connect()` oder `pg_pconnect()` zurückgegeben wird.
$oid Pflicht	int	Die OID (Object Identifier) des Large Objects in der Datenbank, das exportiert werden soll.
$pathname Pflicht	string	Der vollständige Dateipfad auf dem Datenbankserver, in den das Large Object geschrieben werden soll. Die Datei wird erstellt bzw. überschrieben.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültige OID, fehlende Schreibberechtigung oder fehlgeschlagene Transaktion).

Beispiele

Large Object aus der Datenbank in eine Datei exportieren

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

// OID des gespeicherten Large Objects (z. B. zuvor mit pg_lo_import gespeichert)
$oid = 123456;
$zieldatei = '/tmp/exportiertes_bild.jpg';

// Transaktion starten (zwingend erforderlich für Large-Object-Operationen)
pg_query($conn, 'BEGIN');

$erfolg = pg_lo_export($conn, $oid, $zieldatei);

if ($erfolg) {
    pg_query($conn, 'COMMIT');
    echo "Large Object erfolgreich nach {$zieldatei} exportiert.";
} else {
    pg_query($conn, 'ROLLBACK');
    echo 'Fehler beim Exportieren des Large Objects.';
}

pg_close($conn);
?>

Large Object erfolgreich nach /tmp/exportiertes_bild.jpg exportiert.

Large Object importieren und anschließend wieder exportieren

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

// Transaktion starten
pg_query($conn, 'BEGIN');

// Datei in die Datenbank importieren
$quelldatei = '/var/www/uploads/dokument.pdf';
$oid = pg_lo_import($conn, $quelldatei);

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

echo "Large Object importiert, OID: {$oid}\n";

// Dasselbe Objekt wieder exportieren (z. B. zur Überprüfung)
$exportpfad = '/tmp/dokument_backup.pdf';
$erfolg = pg_lo_export($conn, $oid, $exportpfad);

if ($erfolg) {
    pg_query($conn, 'COMMIT');
    echo "Export nach {$exportpfad} erfolgreich.";
} else {
    pg_query($conn, 'ROLLBACK');
    echo 'Export fehlgeschlagen.';
}

pg_close($conn);
?>

Large Object importiert, OID: 123457 Export nach /tmp/dokument_backup.pdf erfolgreich.

// Wichtig · Fallstricke

Transaktion zwingend erforderlich: PostgreSQL erlaubt Large-Object-Operationen nur innerhalb von Transaktionen. Wird pg_lo_export() ohne aktive Transaktion aufgerufen, schlägt die Operation fehl. Stets BEGIN vor dem Aufruf und COMMIT bzw. ROLLBACK danach ausführen.

Dateipfad auf dem Datenbankserver: Der Pfad $pathname bezieht sich auf das Dateisystem des PostgreSQL-Servers, nicht des PHP-Prozesses. In typischen Shared-Hosting-Umgebungen oder verteilten Architekturen kann dies zu Verwirrung führen. Wenn Webserver und Datenbankserver auf verschiedenen Maschinen laufen, ist ein direkter Dateizugriff vom PHP-Skript aus auf die exportierte Datei nicht ohne Weiteres möglich.

Sicherheit: Stelle sicher, dass der PostgreSQL-Prozess (üblicherweise unter dem Benutzer postgres) Schreibrechte auf den Zielordner besitzt. Pfade, die aus Benutzereingaben stammen, müssen sorgfältig validiert werden, um Path-Traversal-Angriffe zu verhindern.

Deprecated-Hinweis: Ab PHP 8.1 wird der Parameter connection nicht mehr optional sein; zuvor konnte die zuletzt geöffnete Verbindung implizit verwendet werden. Seit PHP 8.1 ist der Typ PgSql\Connection ein Objekt statt einer Ressource.

Siehe auch

pg_lo_import pg_lo_open pg_lo_close pg_lo_read pg_lo_write pg_lo_unlink pg_connect