pg_trace — Funktion · PHP-Referenz

Signatur

pg_trace(string $filename, string $mode = 'w', PgSql\Connection|null $connection = null, int $trace_mode = 0): bool

Beschreibung

pg_trace() ermöglicht es, die Kommunikation zwischen PHP und dem PostgreSQL-Server aufzuzeichnen. Alle Pakete, die über das Frontend/Backend-Protokoll ausgetauscht werden, werden in die angegebene Datei geschrieben. Dies ist nützlich, um Fehler in Abfragen zu diagnostizieren, Verbindungsprobleme zu analysieren oder das Verhalten von Datenbankoperationen auf niedriger Ebene zu verstehen.

Die Trace-Ausgabe enthält die rohen Protokollnachrichten im PostgreSQL-Frontend/Backend-Format und ist daher primär für erfahrene Entwickler oder zur tiefen Fehleranalyse gedacht. Das Tracing sollte im Produktionsbetrieb deaktiviert sein, da es die Leistung beeinträchtigt und potenziell sensible Daten (z. B. Passwörter, Abfrageergebnisse) in der Trace-Datei landen können.

Das Tracing wird mit pg_untrace() wieder beendet. Wenn keine Verbindung übergeben wird, verwendet PHP die zuletzt geöffnete Verbindung. Ab PHP 8.1 ist der Parameter $connection vom Typ PgSql\Connection statt resource.

Ab PHP 8.2 kann über den Parameter $trace_mode gesteuert werden, wie Bytewerte in der Ausgabe dargestellt werden (PGSQL_TRACE_SUPPRESS_TIMESTAMPS und PGSQL_TRACE_REGRESS_MODE).

Parameter

Name	Typ	Default	Beschreibung
$filename Pflicht	string		Vollständiger Pfad zur Datei, in die die Trace-Ausgabe geschrieben wird. PHP muss Schreibrechte auf diese Datei bzw. das Verzeichnis besitzen.
$mode	string	w	Dateimodus wie bei `fopen()`, z. B. `'w'` zum Überschreiben oder `'a'` zum Anhängen an eine bestehende Datei.
$connection	PgSql\Connection\|null	null	Eine PostgreSQL-Datenbankverbindung, die mit `pg_connect()` oder `pg_pconnect()` geöffnet wurde. Wird `null` übergeben oder weggelassen, wird die zuletzt geöffnete Verbindung verwendet.
$trace_mode	int	0	Steuert das Format der Trace-Ausgabe. Mögliche Werte sind die Konstanten `PGSQL_TRACE_SUPPRESS_TIMESTAMPS` und `PGSQL_TRACE_REGRESS_MODE` (ab PHP 8.2). Standardmäßig `0` (keine besonderen Einstellungen).

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn das Tracing erfolgreich gestartet wurde, andernfalls false (z. B. wenn die Datei nicht geöffnet werden kann).

Beispiele

Einfache Ablaufverfolgung einer PostgreSQL-Verbindung

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

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

// Tracing starten: alle Protokollnachrichten in /tmp/pg_trace.log schreiben
if (pg_trace('/tmp/pg_trace.log', 'w', $conn)) {
    echo "Tracing gestartet.\n";
} else {
    echo "Tracing konnte nicht gestartet werden.\n";
}

// Eine Abfrage ausführen (wird vollständig protokolliert)
$result = pg_query($conn, 'SELECT version()');
$row = pg_fetch_row($result);
echo 'PostgreSQL-Version: ' . $row[0] . "\n";

// Tracing beenden
pg_untrace($conn);
echo "Tracing beendet. Ausgabe in /tmp/pg_trace.log\n";

pg_close($conn);

Tracing gestartet. PostgreSQL-Version: PostgreSQL 15.3 on x86_64-pc-linux-gnu ... Tracing beendet. Ausgabe in /tmp/pg_trace.log

Tracing mit Anhängen an bestehende Log-Datei

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

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

// Tracing im Append-Modus: vorhandene Trace-Daten bleiben erhalten
pg_trace('/var/log/pg_debug.log', 'a', $conn);

try {
    // Mehrere Abfragen werden vollständig protokolliert
    pg_query($conn, 'SELECT * FROM users WHERE id = 1');
    pg_query($conn, 'SELECT COUNT(*) FROM orders');
} finally {
    // Tracing immer beenden, auch im Fehlerfall
    pg_untrace($conn);
    pg_close($conn);
    echo "Trace-Daten wurden an /var/log/pg_debug.log angehängt.\n";
}

Trace-Daten wurden an /var/log/pg_debug.log angehängt.

// Wichtig · Fallstricke

Sicherheitshinweis: Die Trace-Datei kann hochsensible Informationen enthalten, darunter Passwörter (falls sie als Klartextprotokoll übertragen werden), Abfragedaten und Ergebnismengen. Stellen Sie sicher, dass die Trace-Datei nur für berechtigte Benutzer lesbar ist und nach der Diagnose wieder gelöscht wird.

Leistung: Das Tracing erhöht den I/O-Aufwand erheblich und sollte niemals dauerhaft im Produktionsbetrieb aktiviert sein. Verwenden Sie es ausschließlich zu Diagnosezwecken in Entwicklungs- oder Testumgebungen.

Dateiberechtigungen: PHP (bzw. der Webserver-Prozess) muss Schreibrechte auf den Zieldateipfad besitzen. Andernfalls gibt pg_trace() false zurück und das Tracing wird nicht gestartet.

Ab PHP 8.1 wurde der Typ des Verbindungsparameters von resource auf PgSql\Connection geändert.

Siehe auch

pg_untrace pg_connect pg_last_error pg_query