pg_untrace — Funktion · PHP-Referenz

Signatur

pg_untrace(PgSql\Connection $connection = ?): bool

Beschreibung

pg_untrace() stoppt die Protokollierung der internen Kommunikation zwischen PHP und dem PostgreSQL-Server, die zuvor mit pg_trace() gestartet wurde. Nach dem Aufruf werden keine weiteren Datenbankbefehle und Antworten mehr in die Trace-Datei geschrieben.

Die Funktion ist nützlich, um den Tracing-Bereich gezielt einzugrenzen: Man aktiviert das Tracing nur für einen kritischen Codeabschnitt und deaktiviert es danach sofort wieder, um die Trace-Datei übersichtlich zu halten und die Auswirkungen auf die Performance zu minimieren.

Wird kein $connection-Parameter übergeben, verwendet PHP die zuletzt geöffnete PostgreSQL-Verbindung. In modernen PHP-Versionen (ab PHP 8.1) ist dieser Parameter obligatorisch, da die automatische Verwendung der letzten Verbindung als veraltet gilt.

Parameter

Name	Typ	Default	Beschreibung
$connection	PgSql\Connection		Eine PostgreSQL-Verbindungsinstanz, die von `pg_connect()` oder `pg_pconnect()` zurückgegeben wurde. Wird der Parameter weggelassen, wird die zuletzt geöffnete Verbindung verwendet (ab PHP 8.1 veraltet).

Rückgabewert

Typ

bool

Beschreibung

Gibt immer true zurück.

Beispiele

Tracing eines bestimmten Codeabschnitts aktivieren und danach beenden

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

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

// Tracing starten: Kommunikation wird in /tmp/pg_trace.log geschrieben
pg_trace('/tmp/pg_trace.log', 'w', $conn);

// Datenbankoperation, die protokolliert werden soll
$result = pg_query($conn, 'SELECT id, name FROM users LIMIT 5');
while ($row = pg_fetch_assoc($result)) {
    echo $row['id'] . ': ' . $row['name'] . PHP_EOL;
}

// Tracing beenden – ab hier wird nichts mehr protokolliert
pg_untrace($conn);

// Diese Abfrage erscheint NICHT in der Trace-Datei
$result2 = pg_query($conn, 'SELECT COUNT(*) FROM orders');

pg_close($conn);

1: Alice 2: Bob 3: Charlie 4: Diana 5: Eva

Tracing zur Fehleranalyse einer einzelnen Abfrage

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

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

$traceFile = sys_get_temp_dir() . '/pg_debug_' . getmypid() . '.log';

// Nur die problematische Abfrage tracen
pg_trace($traceFile, 'w', $conn);

$res = pg_query($conn, 'SELECT * FROM non_existing_table');
if (!$res) {
    echo 'Fehler: ' . pg_last_error($conn) . PHP_EOL;
}

pg_untrace($conn);

echo 'Trace-Datei: ' . $traceFile . PHP_EOL;
echo 'Inhalt:' . PHP_EOL . file_get_contents($traceFile) . PHP_EOL;

pg_close($conn);

Fehler: ERROR: relation "non_existing_table" does not exist Trace-Datei: /tmp/pg_debug_12345.log Inhalt: ...

// Wichtig · Fallstricke

Hinweis zur automatischen Verbindung: Das Weglassen des $connection-Parameters ist seit PHP 8.1 als veraltet (deprecated) markiert. Übergeben Sie stets explizit die gewünschte Verbindungsinstanz.

Sicherheit: Trace-Dateien können sensible Daten wie SQL-Abfragen mit Passwörtern oder persönlichen Informationen enthalten. Stellen Sie sicher, dass Trace-Dateien außerhalb des Web-Roots gespeichert und nach der Analyse sofort gelöscht werden. Verwenden Sie niemals pg_trace() in Produktionsumgebungen, ohne anschließend pg_untrace() aufzurufen.

Rückgabewert: Die Funktion gibt immer true zurück, auch wenn zuvor kein aktives Tracing vorhanden war.

Siehe auch

pg_trace pg_connect pg_last_error