pg_lo_truncate — Funktion · PHP-Referenz

Signatur

pg_lo_truncate(PgSql\LargeObject $large_object, int $size): bool

Beschreibung

pg_lo_truncate() verkürzt ein bereits geöffnetes PostgreSQL-Large-Object (LOB) auf die angegebene Anzahl von Bytes. Ist das Large Object größer als $size, gehen die überschüssigen Daten verloren. Ist es kleiner, wird es mit Null-Bytes (\0) auf die gewünschte Länge aufgefüllt – analog zum POSIX-Systemaufruf ftruncate().

Large Objects in PostgreSQL sind Binärobjekte, die in der Systemtabelle pg_largeobject gespeichert werden und über einen OID referenziert werden. Sie eignen sich für das Speichern von Dateien oder großen Binärdaten direkt in der Datenbank. pg_lo_truncate() ermöglicht es, ein solches Objekt gezielt zu kürzen, ohne es komplett löschen und neu anlegen zu müssen.

Die Funktion muss innerhalb einer Transaktion ausgeführt werden, da PostgreSQL-Large-Object-Operationen transaktionssicher sind. Vor dem Aufruf ist das Large Object mit pg_lo_open() im Schreibmodus (PGSQL_INV_WRITE) zu öffnen. Nach der Operation sollte das Objekt mit pg_lo_close() geschlossen und die Transaktion mit pg_query() (COMMIT) abgeschlossen werden.

Typische Anwendungsfälle sind das Bereinigen oder Zurücksetzen von LOB-Inhalten sowie das gezielte Abschneiden von Daten, die durch vorherige Schreiboperationen zu groß geworden sind.

Parameter

Name	Typ	Default	Beschreibung
$large_object Pflicht	PgSql\LargeObject		Ein von `pg_lo_open()` zurückgegebenes Large-Object-Handle. Das Objekt muss im Schreibmodus (`PGSQL_INV_WRITE`) geöffnet worden sein.
$size Pflicht	int		Die gewünschte Zielgröße des Large Objects in Bytes. Muss `>= 0` sein. Bei einem Wert von `0` wird das Objekt vollständig geleert (auf 0 Bytes gekürzt).

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültiges Handle, fehlende Schreibrechte oder kein aktiver Transaktionskontext).

Beispiele

Large Object auf 1024 Bytes kürzen

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

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

// Vorhandenes Large Object per OID öffnen (Schreibmodus)
$oid = 12345; // Beispiel-OID eines vorhandenen LOB
$lo = pg_lo_open($conn, $oid, 'w');

if ($lo === false) {
    pg_query($conn, 'ROLLBACK');
    die('Large Object konnte nicht geöffnet werden.');
}

// Large Object auf 1024 Bytes kürzen
$result = pg_lo_truncate($lo, 1024);

if ($result) {
    echo 'Large Object erfolgreich auf 1024 Bytes gekürzt.' . PHP_EOL;
} else {
    echo 'Fehler beim Kürzen des Large Objects.' . PHP_EOL;
}

pg_lo_close($lo);
pg_query($conn, 'COMMIT');
pg_close($conn);
?>

Large Object erfolgreich auf 1024 Bytes gekürzt.

Large Object vollständig leeren (auf 0 Bytes)

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

pg_query($conn, 'BEGIN');

$oid = 67890; // OID des zu leerenden LOB
$lo = pg_lo_open($conn, $oid, 'w');

if ($lo === false) {
    pg_query($conn, 'ROLLBACK');
    die('Large Object konnte nicht geöffnet werden.');
}

// Auf 0 Bytes kürzen = vollständig leeren
if (pg_lo_truncate($lo, 0)) {
    echo 'Large Object wurde vollständig geleert.' . PHP_EOL;
} else {
    echo 'Fehler beim Leeren des Large Objects.' . PHP_EOL;
}

pg_lo_close($lo);
pg_query($conn, 'COMMIT');
pg_close($conn);
?>

Large Object wurde vollständig geleert.

// Wichtig · Fallstricke

Transaktion erforderlich: PostgreSQL-Large-Object-Operationen sind grundsätzlich transaktionsgebunden. Ohne eine aktive Transaktion (gestartet mit BEGIN) schlägt die Operation fehl oder hat unvorhersehbare Auswirkungen. Stellen Sie sicher, dass nach erfolgreichen Operationen ein COMMIT und im Fehlerfall ein ROLLBACK durchgeführt wird.

Schreibmodus notwendig: Das Large Object muss mit dem Flag PGSQL_INV_WRITE (oder dem Kombinations-Flag PGSQL_INV_READ | PGSQL_INV_WRITE) geöffnet worden sein. Ein im reinen Lesemodus geöffnetes Objekt kann nicht gekürzt werden.

Auffüllen mit Null-Bytes: Wenn $size größer als die aktuelle Länge des Large Objects ist, wird das Objekt mit Null-Bytes (\0) auf die Zielgröße erweitert. Dieses Verhalten entspricht dem POSIX-Standard für ftruncate().

PHP-Version: pg_lo_truncate() ist seit PHP 5.6.0 verfügbar. In PHP 8.1 wurde der Typ des Parameters von resource auf PgSql\LargeObject geändert.

Siehe auch

pg_lo_open pg_lo_close pg_lo_create pg_lo_unlink pg_lo_read pg_lo_write pg_lo_seek pg_lo_tell