PHP Handbuch
ZurückWeiter

CXIX. PostgreSQL Funktionen

Einführung

PostgreSQL ist ein kostenloses Open Source Datenbanksystem. Es wurde ursprünglich im UC Berkeley Computer Science Department entwickelt und hat Pionierarbeit bei objektrelationalen Datenbankkonzepten geleistet, die jetzt Einzug in einige kommerzielle Datenbanken halten. PostgreSQL bietet SQL92/SQL99 Sprachunterstützung, Transaktionen, referentielle Integrität, benutzerdefinierte Funktionen und ein erweiterbares Typkonzept. PostgreSQL ist eine Weiterentwicklung des ursprünglichen Berkeley-Codes.

Anforderungen

Um PostgreSQL benutzen zu können, brauchen Sie mindestens eine Version 6.5 oder später. Um alle Leistungsmerkmale des PostgreSQL-Moduls nutzen zu können, müssen Sie eine Version ab 8.0 haben. PostgreSQL unterstützt viele Zeichencodierungen, einschließlich multibyte character encoding. Die aktuelle Version sowie weitere Informationen über PostgreSQL sind auf den Seiten http://www.postgresql.org/ erhältlich und die ausführliche Dokumentation finden Sie unter PostgreSQL Documentation.

Installation

Um die PostgreSQL-Unterstützung zu aktivieren müssen Sie PHP mit der Option --with-pgsql[=DIR] kompilieren. DIR ist das Basis Installationsverzeichnis von PostgreSQL, normalerweise /usr/local/pgsql. Falls das shared-object-Modul verfügbar ist, kann PostgreSQL mit der extension-Directive in php.ini oder der Funktion dl() geladen werden.

Laufzeit Konfiguration

Das Verhalten dieser Funktionen wird durch Einstellungen in der php.ini beeinflusst.

Tabelle 1. PostgreSQL Konfigurationsoptionen

NameStandardÄnderbarChangelog
pgsql.allow_persistent"1"PHP_INI_SYSTEM 
pgsql.max_persistent"-1"PHP_INI_SYSTEM 
pgsql.max_links"-1"PHP_INI_SYSTEM 
pgsql.auto_reset_persistent"0"PHP_INI_SYSTEMVerfügbar seit PHP 4.2.0.
pgsql.ignore_notice"0"PHP_INI_ALLVerfügbar seit PHP 4.3.0.
pgsql.log_notice"0"PHP_INI_ALLVerfügbar seit PHP 4.3.0.
For further details and definitions of the PHP_INI_* constants, see the Anhang G.

Hier eine kurze Erklärung der Konfigurationsoptionen:

pgsql.allow_persistent boolean

Bestimmt, ob persistente PostgreSQL-Verbindungen zulässig sind.

pgsql.max_persistent integer

Legt die maximale Anzahl persistenter PostgreSQL-Verbindungen pro Prozess fest.

pgsql.max_links integer

Legt Die maximale Anzahl aller PostgreSQL-Verbindungen, einschliesslich der persistenten Verbindungen, pro Prozess fest.

pgsql.auto_reset_persistent integer

Findet ungültige persistente Verbindungen, die mit der Funktion pg_pconnect() geöffnet wurden. Erfordert ein wenig Mehraufwand.

pgsql.ignore_notice integer

Bestimmt, ob Notice-Meldungen vom PostgreSQL-Server ignoriert werden sollen.

pgsql.log_notice integer

Bestimmt, ob Notice-Meldungen vom PostgreSQL-Server protokolliert werden sollen. Die PHP-Direktive pgsql.ignore_notice muss deaktiviert sein, um die Meldungen zu protokollieren.

Resource Typen

Im PostgreSQL-Modul werden zwei Ressource-Typen verwendet: Der erste ist die Verbindungskennung für Datenbankverbindungen, die zweite Ressource ist die Ergebniskennung, die ein Abfrageergebnis enthält.

Vordefinierte Konstanten

Folgende Konstanten werden von dieser Erweiterung definiert und stehen nur zur Verfügung, wenn die Erweiterung entweder statisch in PHP kompiliert oder dynamisch zur Laufzeit geladen wurde.

PGSQL_ASSOC (integer)

Wird an die Funktion pg_fetch_array() übergeben. Gibt ein assoziatives Array zurück, mit den Feldnamen als Indizes und den entsprechenden Werten.

PGSQL_NUM (integer)

Wird an die Funktion pg_fetch_array() übergeben. Gibt eine numerisches Array zurück, mit den Feldnummern als Indizes und den entsprechenden Werten.

PGSQL_BOTH (integer)

Wird an die Funktion pg_fetch_array() übergeben. Gibt ein Array zurück, das sowohl assoziativ (mit den Feldnamen) als auch numerisch (mit den Feldnummern) indiziert ist, und den entsprechenden Werten.

PGSQL_CONNECT_FORCE_NEW (integer)

Wird an die Funktion pg_connect() übergeben, um eine neue Verbindung zu erzwingen, anstatt eine identische, bereits geöffnete Verbindung wieder zu benutzen.

PGSQL_CONNECTION_BAD (integer)

Wird von der Funktion pg_connection_status() zurückgegeben und zeigt an, dass der Status der Datenbankverbindung ungültig ist.

PGSQL_CONNECTION_OK (integer)

Wird von der Funktion pg_connection_status() zurückgegeben und zeigt an, dass der Status der Datenbankverbindung gültig ist.

PGSQL_SEEK_SET (integer)

Wird an die Funktion pg_lo_seek() übergeben. Das Objekt wird von Beginn an durchsucht.

PGSQL_SEEK_CUR (integer)

Wird an die Funktion pg_lo_seek() übergeben. Das Objekt wird ab der aktuellen Position durchsucht.

PGSQL_SEEK_END (integer)

Wird an die Funktion pg_lo_seek() übergeben. Das Objekt wird, ausgehend vom Ende, durchsucht.

PGSQL_EMPTY_QUERY (integer)

Wird von der Funktion pg_result_status() zurückgegeben, wenn der an den Server gesendete String leer war.

PGSQL_COMMAND_OK (integer)

Wird von der Funktion pg_result_status() zurückgegeben. Ein Kommando wurde erfolgreich ausgeführt, aber es wurden keine Daten zurückgegeben.

PGSQL_TUPLES_OK (integer)

Wird von der Funktion pg_result_status() zurückgegeben. Ein Kommando wurde erfolgreich ausgeführt und es wurden Daten (wie etwa ein SELECT oder SHOW) zurückgegeben.

PGSQL_COPY_OUT (integer)

Wird von der Funktion pg_result_status() zurückgegeben. Ein Datentransfer vom Server wurde gestartet.

PGSQL_COPY_IN (integer)

Wird von der Funktion pg_result_status() zurückgegeben. Ein Datentransfer zum Server wurde gestartet.

PGSQL_BAD_RESPONSE (integer)

Wird von der Funktion pg_result_status() zurückgegeben. Die Serverantwort wurde nicht verstanden.

PGSQL_NONFATAL_ERROR (integer)

Wird von der Funktion pg_result_status() zurückgegeben. Ein nicht-fataler Fehler (eine Notiz oder Warnung) ist aufgetreten.

PGSQL_FATAL_ERROR (integer)

Wird von der Funktion pg_result_status() zurückgegeben. Ein fataler Fehler ist aufgetreten.

PGSQL_TRANSACTION_IDLE (integer)

Wird von der Funktion pg_transaction_status() zurückgegeben. Die Verbindung wird momentan nicht benutzt, es findet aktuell keine Transaktion statt.

PGSQL_TRANSACTION_ACTIVE (integer)

Wird von der Funktion pg_transaction_status() zurückgegeben. Die Verbindung wird momentan benutzt. Es wird eine Abfrage ausgeführt, die noch nicht beendet ist.

PGSQL_TRANSACTION_INTRANS (integer)

Wird von der Funktion pg_transaction_status() zurückgegeben. Die Verbindung wird von einer Transaktion benutzt, ist aber momentan nicht aktiv.

PGSQL_TRANSACTION_INERROR (integer)

Wird von der Funktion pg_transaction_status() zurückgegeben. Die Verbindung wurde von einer abgebrochenen Transaktion benutzt und ist momentan nicht aktiv.

PGSQL_TRANSACTION_UNKNOWN (integer)

Wird von der Funktion pg_transaction_status() zurückgegeben. Die Verbindung ist ungültig.

PGSQL_DIAG_SEVERITY (integer)

Wird an die Funktion pg_result_error_field() übergeben. Gibt den Schweregrad des Fehlers zurück. Die Feldinhalte sind ERROR, FATAL oder PANIC (in einer Fehlermeldung) oder WARNING, NOTICE, DEBUG, INFO oder LOG (in einer Notice-Meldung) oder eine lokalisierte Übersetzung davon. Dieses Feld ist immer verfügbar.

PGSQL_DIAG_SQLSTATE (integer)

Wird an die Funktion pg_result_error_field() übergeben. Gibt den SQLSTATE-Code des Fehlers zurück. Der SQLSTATE-Code identifiziert den Typ des aufgetretenen Fehlers. Dieser kann von Anwendungen ausgewertet werden, um entsprechende Operationen auszuführen (beispielsweise Fehlerbehandlungsroutinen), als Reaktion auf einen bestimmten Datenbankfehler. dieses Feld kann nicht lokalisiert werden und ist immer verfügbar.

PGSQL_DIAG_MESSAGE_PRIMARY (integer)

Wird an die Funktion pg_result_error_field() übergeben. Dies ist die primäre, für Menschen lesbare Fehlermeldung (normalerweise in einer Zeile) und ist immer verfügbar.

PGSQL_DIAG_MESSAGE_DETAIL (integer)

Wird an die Funktion pg_result_error_field() übergeben. Detail: eine optionale untergeordnete Fehlermeldung, in der das Problem genauer beschrieben wird. Diese Meldung kann mehrere Zeilen lang sein.

PGSQL_DIAG_MESSAGE_HINT (integer)

Wird an die Funktion pg_result_error_field() übergeben. Hint: ein optionaler Hinweis, wie mit dem Problem umzugehen ist. Dies wurde eingeführt, um (möglicherweise unpassende) Lösungen zur Verfügung zu stellen, anstatt harte Fakten, wie bei Details. Diese Meldung kann mehrere Zeilen lang sein.

PGSQL_DIAG_STATEMENT_POSITION (integer)

Wird an die Funktion pg_result_error_field() übergeben. Dies ist ein String, der eine dezimale Integerzahl enthält, die die Cursorposition des originalen SQL-Strings angibt, an der ein Fehler auftrat. Das erste Zeichen hat die Position 1 und zur Bestimmung der Positionen werden Zeichen zugrundegelegt und nicht Bytes.

PGSQL_DIAG_INTERNAL_POSITION (integer)

Wird an die Funktion pg_result_error_field() übergeben. Per Definition ist das dasselbe wie das Feld PG_DIAG_STATEMENT_POSITION, es wird aber benutzt, wenn die Cursorposition auf ein intern generiertes Kommando verweist und nicht auf eines, das vom Benutzer eingegeben wurde. Das Feld PG_DIAG_INTERNAL_QUERY wird immer gesetzt, wenn dieses Feld gesetzt ist.

PGSQL_DIAG_INTERNAL_QUERY (integer)

Wird an die Funktion pg_result_error_field() übergeben. Dies ist der Text eines fehlgeschlagenen, intern generierten Kommandos. Das kann beispielsweise eine SQL-Abfrage sein, die von einer PL/pgSQL-Funktion gesendet wurde.

PGSQL_DIAG_CONTEXT (integer)

Wird an die Funktion pg_result_error_field() übergeben. Dies gibt einen Hinweis auf den Kontext, in dem ein Fehler auftrat. Gegenwärtig sind Zurückverfolgungen des Aufrufstacks von Funktionen aktivierter prozeduraler Sprachen darin enthalten, sowie intern generierte Abfragen. Die Ablaufverfolgung enthält einen Eintrag pro Zeile, die neuesten Einträge zuerst.

PGSQL_DIAG_SOURCE_FILE (integer)

Wird an die Funktion pg_result_error_field() übergeben. Dies ist der Name der Datei im PostgreSQL Quellcode, bei der der Fehler gemeldet wurde.

PGSQL_DIAG_SOURCE_LINE (integer)

Wird an die Funktion pg_result_error_field() übergeben. Die Zeilennummer in der Datei im PostgreSQL Quellcode, bei der der Fehler gemeldet wurde.

PGSQL_DIAG_SOURCE_FUNCTION (integer)

Wird an die Funktion pg_result_error_field() übergeben. Der Name der Funktion im PostgreSQl-Quellcode, bei der der Fehler gemeldet wurde.

PGSQL_ERRORS_TERSE (integer)

Wird an die Funktion pg_set_error_verbosity() übergeben. Damit wird festgelegt, dass Fehlermeldungen die Felder severity, primary text und position enthalten. Normalerweise passt das alles in eine Zeile.

PGSQL_ERRORS_DEFAULT (integer)

Wird an die Funktion pg_set_error_verbosity() übergeben. Die Standardeinstellung gibt Meldungen mit den oben beschriebenen Inhalten zurück, zuzüglich aller Details, Hinweise und Kontext-Informationen. (Dies kann mehrere Zeilen umfassen.)

PGSQL_ERRORS_VERBOSE (integer)

Wird an die Funktion pg_set_error_verbosity() übergeben. In diesem Modus werden alle verfügbaren Felder zurückgegeben.

PGSQL_STATUS_LONG (integer)

Wird an die Funktion pg_result_status() übergeben. Zeigt an, dass ein numerischer Ergebniscode gewünscht ist.

PGSQL_STATUS_STRING (integer)

Wird an die Funktion pg_result_status() übergeben. Zeigt an, dass eine textuelles Ergebnis gewünscht ist.

PGSQL_CONV_IGNORE_DEFAULT (integer)

Wird an die Funktion pg_convert() übergeben. Während der Konversion werden Standardwerte in der Tabelle ignoriert.

PGSQL_CONV_FORCE_NULL (integer)

Wird an die Funktion pg_convert() übergeben. Anstelle eines leeren Strings string wird der SQL Nullwert NULL benutzt.

PGSQL_CONV_IGNORE_DEFAULT (integer)

Wird an die Funktion pg_convert() übergeben. Die Konversion von NULL in SQL NOT NULL-Spalten wird ignoriert.

Anmerkungen

Anmerkung: Nicht alle Funktionen sind in allen Versionen verfügbar. Es hängt davon ab, welche libpq Version (das PostgreSQL C Client Interface) auf Ihrem Rechner verfügbar ist und wie libpq kompiliert wurde. Falls eine Funktion nicht verfügbar ist, liegt es daran, dass libpq die nötigen Routinen nicht unterstützt, die die Funktion braucht.

Anmerkung: Die meisten PostgreSQL Funktionen nehmen den Parameter connection als ersten optionalen Parameter entgegen. Falls er nicht angegeben wurde, wird die zuletzt geöffnete Verbindung benutzt. Wenn keine geöffnete Verbindung existiert, geben diese Funktionen FALSE zurück.

Anmerkung: PostgreSQL wandelt automatisch alle Bezeichner in Kleinbuchstaben um (beispielsweise Tabellennamen oder Spaltennamen) und zwar sowohl bei der Erzeugung der Objekte als auch in Abfragen. Um Namen in Gross- und Kleinschreibung oder in Grossbuchstaben zu erzwingen, müssen diese in Anführungszeichen ("") eingeschlossen werden.

Anmerkung: PostgreSQL stellt keine speziellen Kommandos zur Verfügung, um Informationen über ein Datenbank-Schema (z. B. alle Tabellen in der aktuellen Datenbank) zu erhalten. Stattdessen gibt es ab der Version 7.4 und höher ein Standard-Schma, das information_schema, in dem alle notwendigen Informationen in System-Views enthalten sind und die einfach abzufragen sind. Ausführliche Informationen darüber gibt es in der PostgreSQL Documentation.

Beispiele

Dieses einfache Beispiel zeigt den Verbindungsaufbau, die Ausführung einer einfachen Abfrage, die Ausgabe der Abfrageergebnisse und, wie eine Verbindung wieder geschlossen wird.

Beispiel 1. PostgreSQL extension overview example

<?php
// Verbindungsaufbau und Auswahl der Datenbank
$dbconn = pg_connect("host=localhost dbname=publishing user=www password=foo")
    or die('Verbindungsaufbau fehlgeschlagen: ' . pg_last_error());

// Eine SQL-Abfrge ausführen
$query = 'SELECT * FROM authors';
$result = pg_query($query) or die('Abfrage fehlgeschlagen: ' . pg_last_error());

// Ergebnisse in HTML ausgeben
echo "<table>\n";
while ($line = pg_fetch_array($result, null, PGSQL_ASSOC)) {
    echo "\t<tr>\n";
    foreach ($line as $col_value) {
        echo "\t\t<td>$col_value</td>\n";
    }
    echo "\t</tr>\n";
}
echo "</table>\n";

// Speicher freigeben
pg_free_result($result);

// Verbindung schliessen
pg_close($dbconn);
?>

Inhaltsverzeichnis
pg_affected_rows -- Gibt die Anzahl betroffener Datensätze (Tupel) zurück
pg_cancel_query -- Löscht eine asynchrone Abfrage
pg_client_encoding --  Gibt die Kodierung des Clients zurück
pg_close -- Schließt eine PostgreSQL-Verbindung
pg_connect -- Öffnet eine PostgreSQL Verbindung
pg_connection_busy --  Gibt den Status der Verbindung zurück (busy/not busy)
pg_connection_reset --  Setzt die Verbindung zurück und verbindet neu
pg_connection_status --  Gibt den Verbindungsstatus zurück
pg_convert --  Konvertiert die Werte eines assoziativen Arrays in passende Werte für SQL-Kommandos.
pg_copy_from --  Fügt Datensätze aus einem Array in eine Tabelle ein
pg_copy_to --  Kopiert eine Tabelle in ein Array
pg_dbname -- Gibt den Namen der Datenbank zurück
pg_delete --  Löscht Datensätze
pg_end_copy -- Synchronisation mit dem PostgreSQL-Server
pg_escape_bytea --  Maskiert Binärdaten zum Einfügen in ein Feld vom Typ bytea
pg_escape_string --  Maskiert einen String zum Einfügen in Felder mit text/char Datentypen
pg_execute -- Fordert den Datenankserver auf, eine vorbereitete Anfrage mit den angegebenen Parametern auszuführen und wartet auf das Ergebnis.
pg_fetch_all_columns -- Gibt alle Werte einer bestimmten Spalte eines Abfrageergebnisses in einem Array zurück
pg_fetch_all -- Gibt alle Zeilen eines Abfrageergebnisses als Array zurück.
pg_fetch_array -- Holt eine Zeile als Array
pg_fetch_assoc -- Holt eine Zeile als assoziatives Array
pg_fetch_object -- Holt einen Datensatz als Objekt
pg_fetch_result -- Liefert Werte aus einer Ergebnismenge
pg_fetch_row -- Holt einen Datensatz als numerisches Array
pg_field_is_null -- Prüft, ob ein Feld einen SQL NULL-Wert enthält
pg_field_name -- Gibt den Namen eines Feldes zurück
pg_field_num -- Gibt die Feldnummer des angegebenen Feldes zurück
pg_field_prtlen -- Gibt die Länge des Feldes zurück
pg_field_size --  Gibt den belegten Speicher für ein Feld zurück
pg_field_table -- Returns the name or oid of the tables field
pg_field_type_oid --  Gibt die ID des PostgreSQL-Datentyps (OID) eines Feldes zurück
pg_field_type --  Gibt den Datentyp eines Feldes zurück
pg_free_result -- Gibt den durch Ergebnisse belegten Speicher frei
pg_get_notify -- Gibt eine SQL NOTIFY-Nachricht zurück
pg_get_pid -- Prüft die Datenbankverbindung
pg_get_result --  Gibt asynchrone Abfrageergebnisse zurück
pg_host --  Gibt den Namen des Host zurück, zu dem verbunden wurde
pg_insert --  Überträgt Werte aus einem Array in eine Tabelle
pg_last_error -- Gibt die letzte Fehlermeldung einer Verbindung zurück
pg_last_notice --  Gibt die letzte NOTICE-Meldung des PostgreSQL-Servers zurück
pg_last_oid -- Gibt den Objektbezeichner (OID) des zuletzt eingefügten Datensatzes zurück
pg_lo_close -- Schließt ein Large Object
pg_lo_create -- Erzeugt ein Large Object
pg_lo_export -- Exportiert ein Large Object in eine Datei
pg_lo_import -- Importiert ein Large Object aus einer Datei
pg_lo_open -- Öffnet ein Large Object
pg_lo_read_all --  Liest ein Large Object vollständig und reicht es direkt an den Browser weiter
pg_lo_read -- Liest ein Large Object
pg_lo_seek --  Setzt die Lese- oder Schreibposition in einem Large Object
pg_lo_tell --  Gibt die aktuelle Lese- oder Schreibposition in einem Large Object zurück
pg_lo_unlink -- Löscht ein Large Object
pg_lo_write -- Schreibt in ein Large Object
pg_meta_data --  Gibt Metadaten einer Tabelle als Array zurück
pg_num_fields -- Gibt die Anzahl der Felder in einem Abfrageergebnis zurück
pg_num_rows -- Gibt die Anzahl der Zeilen in einem Abfrageergebnis zurück
pg_options -- Gibt die Verbindungsoptionen der aktuellen Verbindung zurück
pg_parameter_status -- Gibt den Wert einer aktuellen Server-Einstellung zurück.
pg_pconnect -- Öffnet eine persistente PostgreSQL-Verbindung
pg_ping -- Prüft die Datenbankverbindung
pg_port --  Gibt die Portnummer zurück, über die die Verbindung aufgebaut wurde
pg_prepare --  Sendet eine Aufforderung an den Server, eine vorbereitete Anfrage mit den übergebenen Parametern zu erzeugen und wartet auf ihre Beendigung.
pg_put_line -- Sendet eine NULL-terminierte Zeichenkette zum PostgreSQL-Server
pg_query_params -- Sendet ein Kommando zum Server und wartet seine Ausführung ab. Getrennt vom SQL-Kommando können dabei Parameter übergeben werden.
pg_query -- Führt eine Abfrage aus
pg_result_error_field -- Gibt den Inhalt eines bestimmtes Feldes zu einer Fehlermeldung zurück.
pg_result_error --  Gibt die mit der Ergebniskennung verknüpfte Fehlermeldung zurück
pg_result_seek -- Setzt den internen Datensatzzeiger auf die angegebene Position in einem Abfrageergebnis
pg_result_status --  Gibt den Status eines Abfrageergebnisses zurück
pg_select --  Wählt Datensätze aus
pg_send_execute --  Sendet eine Aufforderung an den Server, eine vorbereitete Abfrage mit den übergebenen Parametern auszuführen, ohne auf die Ergebnisse zu warten.
pg_send_prepare --  Sendet eine Aufforderung an den Server, eine vorbereitete Abfrage mit den übergebenen Parametern zu erzeugen, ohne auf ihre Beendigung zu warten.
pg_send_query_params -- Sendet ein Kommando und separate Parameter zum Server, ohne auf die Rückgabe der Ergebnisse zu warten.
pg_send_query --  Sendet eine asynchrone Abfrage
pg_set_client_encoding --  Setzt die Kodierung des Clients
pg_set_error_verbosity --  Bestimmt den Detaillierungsgrad von Fehlermeldungen, die von pg_last_error() und pg_result_error() zurückgegeben werden.
pg_trace -- Ermöglicht die Ablaufverfolgung einer Verbindung
pg_transaction_status -- Gibt den aktuellen Transaktionsstatus des Servers zurück.
pg_tty --  Gibt den TTY Namen für die Verbindung zurück
pg_unescape_bytea --  Entfernt Maskierungen für den Typ bytea
pg_untrace -- Beendet die Ablaufverfolgung einer PostgreSQL-Verbindung
pg_update --  Aktualisiert eine Tabelle
pg_version --  Gibt ein Array zurück, das die Versionen von Client, Protokoll und Server zurückgibt (falls verfügbar)
ZurückZum AnfangWeiter
sql_regcaseNach obenpg_affected_rows