pg_lo_unlink — Funktion · PHP-Referenz

Signatur

pg_lo_unlink(PgSql\Connection $connection, int $oid): bool

Beschreibung

pg_lo_unlink() entfernt ein Large Object (LO) dauerhaft aus der PostgreSQL-Datenbank. Large Objects werden in der Systemtabelle pg_largeobject gespeichert und sind über eine eindeutige OID (Object Identifier) referenzierbar. Diese Funktion löscht das Objekt vollständig, sodass die OID anschließend nicht mehr gültig ist.

Die Funktion muss innerhalb einer Transaktion aufgerufen werden. Das bedeutet, vor dem Aufruf muss entweder explizit mit pg_query($conn, 'BEGIN') eine Transaktion gestartet worden sein oder Auto-Commit muss deaktiviert sein. Wird außerhalb einer Transaktion aufgerufen, schlägt die Operation fehl.

Typische Anwendungsfälle sind das Aufräumen von nicht mehr benötigten Binärdaten (z. B. hochgeladene Dateien, Bilder oder Dokumente), die zuvor mit pg_lo_import() oder pg_lo_create() angelegt wurden. Es ist sinnvoll, diese Funktion zu verwenden, wenn Large Objects als Alternative zu BYTEA-Feldern für sehr große Binärdaten eingesetzt werden.

Wichtig: Werden Large Objects in der Datenbank referenziert (z. B. durch Fremdschlüssel in eigenen Tabellen), sollte die Referenz vor dem Löschen entfernt werden, um inkonsistente Daten zu vermeiden. PostgreSQL bietet hier keinen automatischen Referenzintegritätsschutz für Large Objects.

Parameter

Name	Typ	Default	Beschreibung
$connection Pflicht	PgSql\Connection		Eine aktive PostgreSQL-Datenbankverbindung, wie sie von `pg_connect()` oder `pg_pconnect()` zurückgegeben wird.
$oid Pflicht	int		Die OID (Object Identifier) des Large Objects, das gelöscht werden soll. Diese OID wurde beim Erstellen des Objekts (z. B. via `pg_lo_import()` oder `pg_lo_create()`) vergeben.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn das Large Object erfolgreich gelöscht wurde, andernfalls false. Ein Fehler tritt z. B. auf, wenn die OID nicht existiert, die Verbindung ungültig ist oder keine aktive Transaktion vorliegt.

Beispiele

Large Object nach dem Erstellen wieder löschen

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

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

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

// Large Object aus einer Datei importieren
$oid = pg_lo_import($conn, '/tmp/beispiel.pdf');

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

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

// Large Object wieder löschen
if (pg_lo_unlink($conn, $oid)) {
    echo "Large Object mit OID $oid erfolgreich gelöscht.\n";
    pg_query($conn, 'COMMIT');
} else {
    echo "Fehler beim Löschen des Large Objects.\n";
    pg_query($conn, 'ROLLBACK');
}

pg_close($conn);
?>

Large Object erstellt mit OID: 16842 Large Object mit OID 16842 erfolgreich gelöscht.

OID aus einer Tabelle auslesen und zugehöriges Large Object löschen

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

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

// Datensatz mit gespeicherter OID aus eigener Tabelle abrufen
$result = pg_query($conn, "SELECT id, dokument_oid FROM dokumente WHERE id = 42");
$row = pg_fetch_assoc($result);

if (!$row) {
    die('Datensatz nicht gefunden');
}

$oid = (int) $row['dokument_oid'];

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

// Datensatz aus der eigenen Tabelle löschen
pg_query($conn, "DELETE FROM dokumente WHERE id = 42");

// Large Object aus pg_largeobject löschen
if (pg_lo_unlink($conn, $oid)) {
    pg_query($conn, 'COMMIT');
    echo "Dokument und Large Object (OID: $oid) erfolgreich entfernt.\n";
} else {
    pg_query($conn, 'ROLLBACK');
    echo "Fehler: Large Object konnte nicht gelöscht werden. Rollback durchgeführt.\n";
}

pg_close($conn);
?>

Dokument und Large Object (OID: 24601) erfolgreich entfernt.

// Wichtig · Fallstricke

Transaktionspflicht: PostgreSQL verlangt, dass alle Large-Object-Operationen – einschließlich pg_lo_unlink() – innerhalb einer aktiven Transaktion stattfinden. Ohne vorheriges BEGIN wird die Funktion fehlschlagen.

Berechtigungen: Nur der Eigentümer des Large Objects oder ein Superuser darf es löschen. Andere Benutzer erhalten einen Berechtigungsfehler.

Keine referenzielle Integrität: PostgreSQL prüft nicht, ob die OID noch in anderen Tabellen referenziert wird. Nach dem Löschen enthaltene OID-Referenzen zeigen auf nicht mehr vorhandene Objekte – dies kann zu Datenverlust oder Inkonsistenzen führen. Eigene Tabelleneinträge sollten daher immer in derselben Transaktion bereinigt werden.

Ab PHP 8.1: Der Parameter $connection erwartet eine Instanz von PgSql\Connection statt einer Ressource.

Siehe auch

pg_lo_create pg_lo_import pg_lo_export pg_lo_open pg_lo_close pg_connect