Manuel PHP
Précédent		Suivant

CXI. PostgreSQL

Introduction

La base de données PostgreSQL est un produit Open Source, disponible sans frais. PostgreSQL, développé au département de Science informatique, à UC Berkeley, met en place la majorité des concepts des bases relationnelles actuellement disponibles sur le marché. PostgreSQL accepte le langage SQL92/SQL3, assure l'intégrité transactionnelle et l'extension de type. PostgreSQL est une évolution du code original de Berkeley.

Pré-requis

Pour accéder au support PostgreSQL, vous avez besoin de PostgreSQL 6.5 ou plus récent ; PostgreSQL 7.0 ou plus récent pour activer toutes les fonctionnalités du module PostgreSQL. PostgreSQL supporte de nombreux jeux de caractères, y compris les jeux multi-octets asiatiques. La version courante et plus de détails sur PostgreSQL sont accessibles sur le site http://www.postgresql.org/ et la Documentation PostgreSQL.

Installation

Afin d'activer le support PostgreSQL, l'option --with-pgsql[=DIR] est nécessaire lors de la compilation de PHP. DIR est le chemin du dossier d'installation de PostgreSQL, et par défaut il vaut /usr/local/pgsql. Si le module de chargement dynamique est disponible, le module PostgreSQL peut être chargé avec la directive extension du fichier php.ini ou via la fonction dl().

Configuration à l'exécution

Le comportement de ces fonctions est affecté par la configuration dans le fichier php.ini.

Tableau 1. Options de configuration

Nom	Par défaut	Modifiable	Historique
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_SYSTEM	Disponible depuis PHP 4.2.0.
pgsql.ignore_notice	"0"	PHP_INI_ALL	Disponible depuis PHP 4.3.0.
pgsql.log_notice	"0"	PHP_INI_ALL	Disponible depuis PHP 4.3.0.

Pour plus de détails sur les constantes PHP_INI_*, reportez-vous à Annexe H.

Voici un éclaircissement sur l'utilisation des directives de configuration.

pgsql.allow_persistent booléen: Autorise ou non les connexions persistantes Postgre.
pgsql.max_persistent entier: Le nombre maximum de connexions persistantes Postgre par processus.
pgsql.max_links entier: Le nombre maximum de connexions Postgre par processus, y compris les connexions persistantes.
pgsql.auto_reset_persistent entier: Détecte les connexions persistantes (ouvertes avec pg_pconnect()) rompues.
pgsql.ignore_notice entier: Active ou non l'affichage des notices PostgreSQL.
pgsql.log_notice entier: Active ou non l'enregistrement en fichier log des messages notices PostgreSQL. La directive PHP pgsql.ignore_notice doit être désactivée pour pouvoir enregistrer les messages de notices en fichier log.

Trucs et astuces d'utilisation

Avertissement

Utiliser le module PostgreSQL avec PHP 4.0.6 n'est pas recommandé à cause d'un bogue dans le gestionnaire d'alerte. Utilisez plutôt la version 4.1.0 ou plus récente.

Avertissement

Le nom des fonctions PostgreSQL va changer dans la version 4.2.0 pour prendre en compte les standards actuels de programmation. La plupart des nouveaux noms recevront des soulignés, comme pg_lo_open(). Certaines fonctions sont renommées différemment, comme pg_exec() en pg_query(). Les anciens noms sont toujours utilisés pour encore quelques versions, mais ils seront bientôt supprimés définitivement.

Tableau 2. Noms des fonctions qui ont changé

Ancien nom	Nouveau nom
pg_cmdtuples()	pg_affected_rows()
pg_errormessage()	pg_last_error()
pg_exec()	pg_query()
pg_fieldname()	pg_field_name()
pg_fieldsize()	pg_field_size()
pg_fieldnum()	pg_field_num()
pg_fieldprtlen()	pg_field_prtlen()
pg_fieldisnull()	pg_field_is_null()
pg_freeresult()	pg_free_result()
pg_getlastoid()	pg_last_oid()
pg_loreadall()	pg_lo_read_all()
pg_locreate()	pg_lo_create()
pg_lounlink()	pg_lo_unlink()
pg_loopen()	pg_lo_open()
pg_loclose()	pg_lo_close()
pg_loread()	pg_lo_read()
pg_lowrite()	pg_lo_write()
pg_loimport()	pg_lo_import()
pg_loexport()	pg_lo_export()
pg_numrows()	pg_num_rows()
pg_numfields()	pg_num_fields()
pg_result()	pg_fetch_result()

Les anciennes syntaxes de pg_connect()/pg_pconnect() seront rendues obsolètes pour supporter les nouvelles connexions asynchrones. Utilisez la chaîne de connexion avec pg_connect() et pg_pconnect().

Toutes les fonctions ne sont pas supportées par toutes les compilations. Cela dépend de votre bibliothèque libpq (la bibliothèque C client de PostgreSQL), et comment libpq est compilé. S'il y a des fonctions qui manquent, libpq ne supporte par la fonctionnalité sur laquelle reposait la fonction n'est pas disponible.

Il est aussi important que vous utilisiez une version de libpq qui soit plus récente que le serveur sur lequel vous vous connectez. Si vous utilisez une version de libpq plus ancienne que le serveur, vous aurez des problèmes.

Depuis la version 6.3 (03/02/1998), PostgreSQL utilise les sockets UNIX, et une table est dédiée à ces nouvelles capacités. La socket est située dans le dossier /tmp/.s.PGSQL.5432. Cette option peut être activée avec '-i' passé au postmaster et cela s'interprète : "écoute sur les sockets TCP/IP et sur les sockets Unix".

Tableau 3. Postmaster et PHP

Postmaster	PHP	Statut
postmaster &	`pg_connect("dbname=MyDbName");`	OK
postmaster -i &	`pg_connect("dbname=MyDbName");`	OK
postmaster &	`pg_connect("host=localhost dbname=MyDbName");`	`Unable to connect to PostgreSQL server: connectDB() failed:` Impossible de se connecter au serveur PostgreSQL : connectDB() a échoué. Est-ce que le postmaster fonctionne, et accepte les TCP/IP (option -i) sur le port '5432'?
postmaster -i &	`pg_connect("host=localhost dbname=MyDbName");`	OK

Il est possible de se connecter avec la commande suivante : $conn = pg_Connect("host=monHote port=monPort tty=monTTY options=myOptions dbname=myDB user=myUser password=myPassword");

L'ancienne syntaxe : $conn = pg_connect("host", "port", "options", "tty", "dbname") est obsolète.

Les variables environnementales affectent le comportement de PostgreSQL. Par exemple, le module PostgreSQL va rechercher PGHOST dans les variables d'environnement, si le nom du serveur hôte est omis dans la chaîne de connexion. Les variables d'environnement supportées sont différentes suivant les versions. Reportez-vous au manuel du programmeur PostgreSQL (libpq - Environment Variables) pour plus de détails.

Assurez-vous que vous avez bien configuré vos variables d'environnement pour le bon utilisateur. Utilisez $_ENV ou getenv() pour vérifier quelles variables d'environnement sont disponibles pour le processus courant.

Exemple 1. Configuration par défaut des paramètres

PGHOST=pgsql.example.com
PGPORT=7890
PGDATABASE=web-system
PGUSER=web-user
PGPASSWORD=secret
PGDATESTYLE=ISO
PGTZ=JST
PGCLIENTENCODING=EUC-JP

export PGHOST PGPORT PGDATABASE PGUSER PGPASSWORD PGDATESTYLE PGTZ PGCLIENTENCODING

Note : PostgreSQL transforme automatiquement tous les identifiants (e.g. les noms de table/colonnes) en minuscule. Pour lui faire reconnaître les valeurs en majuscules, vous devez toujours entourer l'identifiant de simples guillemets.

Constantes pré-définies

Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.

PGSQL_ASSOC (entier): Passée à pg_fetch_array(). Retourne un tableau associatif des noms et valeurs des champs.
PGSQL_NUM (entier): Passée à pg_fetch_array(). Retourne un tableau à index numérique des numéros et valeurs des champs.
PGSQL_BOTH (entier): Passée à pg_fetch_array(). Retourne un tableau des valeurs des champs qui est indexés numériquement (par le numéro des champs) et indexés associativement (par le nom des champs).
PGSQL_CONNECT_FORCE_NEW (entier): Passée à pg_connect() pour forcer la création d'une nouvelle connexion, plutôt que de réutiliser une connexion identique existante.
PGSQL_CONNECTION_BAD (entier): Retournée par pg_connection_status() indiquant que la connexion à la base de données est invalide.
PGSQL_CONNECTION_OK (entier): Retournée par pg_connection_status() indiquant que la connexion à la base de données est valide.
PGSQL_SEEK_SET (entier): Passée à pg_lo_seek(). Le positionnement commencera au début de l'objet.
PGSQL_SEEK_CUR (entier): Passée à pg_lo_seek(). Le positionnement commencera à la position courante.
PGSQL_SEEK_END (entier): Passée à pg_lo_seek(). Le positionnement commencera à la fin de l'objet.
PGSQL_EMPTY_QUERY (entier): Retournée par pg_result_status(). La chaîne de caractères envoyée au serveur était vide.
PGSQL_COMMAND_OK (entier): Retournée par pg_result_status(). Commande correctement complétée ne retournant aucune donnée.
PGSQL_TUPLES_OK (entier): Retournée par pg_result_status(). Commande correctement complétée retournant des données (comme SELECT ou SHOW).
PGSQL_COPY_OUT (entier): Retournée par pg_result_status(). Copie (à partir du serveur) de transfert de données commencée.
PGSQL_COPY_IN (entier): Retournée par pg_result_status(). Copie (vers le serveur) de transfert de données commencée.
PGSQL_BAD_RESPONSE (entier): Retournée par pg_result_status(). La réponse du serveur n'a pas été comprise.
PGSQL_NONFATAL_ERROR (entier): Retournée par pg_result_status(). Une erreur non fatale (de niveau notice ou warning) s'est produite.
PGSQL_FATAL_ERROR (entier): Retournée par pg_result_status(). Une erreur fatale s'est produite.
PGSQL_TRANSACTION_IDLE (entier): Retournée par pg_transaction_Status(). La connexion est présentement libre, aucune transaction en cours.
PGSQL_TRANSACTION_ACTIVE (entier): Retournée par pg_transaction_status(). Une commande est en cours sur la connexion. Une requête a été envoyée sur la connexion et n'a toujours pas été complétée.
PGSQL_TRANSACTION_INTRANS (entier): Retournée par pg_transaction_status(). La connexion est libre, dans un bloc de transaction.
PGSQL_TRANSACTION_INERROR (entier): Retournée par pg_transaction_status(). La connexion est libre, dans un bloc de transaction échoué.
PGSQL_TRANSACTION_UNKNOWN (entier): Retournée par pg_transaction_status(). La connexion est mauvaise.
PGSQL_DIAG_SEVERITY (entier): Passée à pg_result_error_field(). La sévérité; le contenu du champ est ERROR, FATAL ou PANIC (dans un message d'erreur) ou WARNING, NOTICE, DEBUG, INFO ou LOG (dans un message d'avertissement) ou une traduction localisée parmi celles-ci. Toujours présent.
PGSQL_DIAG_SQLSTATE (entier): Passée à pg_result_error_field(). Le code SQLSTATE pour cette erreur. Le code SQLSTATE identifie le type d'erreur qui s'est produite; cela peut être utilisé par des applications d'entrée pour effectuer des opérations spécifiques (comme la gestion d'erreur) en réponse à une erreur de base de données particulière. Ce champ ne peut être localisé et est toujours présent.
PGSQL_DIAG_MESSAGE_PRIMARY (entier): Passée à pg_result_error_field(). Le champ d'erreur primaire interprétable pour l'utilisateur (normalement une ligne). Toujours présent.
PGSQL_DIAG_MESSAGE_DETAIL (entier): Passée à pg_result_error_field(). Détail : un second optionnel message d'erreur apportant plus de détails à propos du problème. Peut être sur plusieurs lignes.
PGSQL_DIAG_MESSAGE_HINT (entier): Passée à pg_result_error_field(). Conseil : une suggestion optionnelle qui indique que faire à propos du problème. Ceci est prévu d'être différent de l'erreur puisqu'elle offre un conseil (potentiellement inadéquat) plutôt que les faits véridiques. Peut être sur plusieurs lignes.
PGSQL_DIAG_STATEMENT_POSITION (entier): Passée à pg_result_error_field(). Une chaîne de caractères contenant une valeur entière décimale indiquant une erreur de position du curseur en tant qu'index dans la requête originale. Le premier caractère a l'index 1 et les positions sont mesurées en caractères, non en octets.
PGSQL_DIAG_INTERNAL_POSITION (entier): Passée à pg_result_error_field(). Ceci est défini étant la même chose que le champ PG_DIAG_STATEMENT_POSITION, mais cela est utilisé lorsque la position du curseur réfère à une commande générée internement plutôt que d'une envoyée par le client. Le champ PG_DIAG_INTERNAL_QUERY apparaîtra toujours lorsque ce champ apparaît.
PGSQL_DIAG_INTERNAL_QUERY (entier): Passée à pg_result_error_field(). Le texte d'une commande générée internement échouée. Cela peut être, par exemple, une requête SQL envoyée par une fonction PL/pgSQL.
PGSQL_DIAG_CONTEXT (entier): Passée à pg_result_error_field(). Une indication du contexte dans lequel l'erreur s'est produit. Présentement, ceci inclue une pile d'appel des traceback des fonctions procédurales actives ainsi que des requête générées à l'interne. Le traçage est une entrée par ligne, les plus récentes en premier.
PGSQL_DIAG_SOURCE_FILE (entier): Passée à pg_result_error_field(). Le nom du fichier de l'emplacement du code source PostgreSQL où l'erreur a été reportée.
PGSQL_DIAG_SOURCE_LINE (entier): Passée à pg_result_error_field(). Le nombre de ligne de l'emplacement du code source PostgreSQL où l'erreur a été reportée.
PGSQL_DIAG_SOURCE_FUNCTION (entier): Passée à pg_result_error_field(). Le nom de la fonction de source code PostgreSQL reportant l'erreur.
PGSQL_ERRORS_TERSE (entier): Passée à pg_set_error_verbosity(). Spécifie que les messages retournés incluent la sévérité, le texte primaire ainsi que la position seulement; ceci devrait entrer sur une seule ligne.
PGSQL_ERRORS_DEFAULT (entier): Passée à pg_set_error_verbosity(). Le mode par défaut produit des messages qui incluent ce qui est plus haut et des détails en plus, conseil ou des champs contextes (ceci peut être sur plusieurs lignes).
PGSQL_ERRORS_VERBOSE (entier): Passée à pg_set_error_verbosity(). Le mode verbeux inclue tous les champs disponibles.
PGSQL_STATUS_LONG (entier): Passée à pg_result_status(). Indique que le code résultat est désiré numérique.
PGSQL_STATUS_STRING (entier): Passée à pg_result_status(). Indique que le tag de résultat de commande est désiré textuel.
PGSQL_CONV_IGNORE_DEFAULT (entier): Passée à pg_convert(). Ignore les valeurs par défaut dans la table pendant la conversion.
PGSQL_CONV_FORCE_NULL (entier): Passée à pg_convert(). Utilise NULL à la place d'une chaîne de caractères vide.
PGSQL_CONV_IGNORE_DEFAULT (entier): Passée à pg_convert(). Ignore la conversion de NULL à l'intérieur des colonnes NOT NULL.

Exemples

Depuis PostgreSQL 7.1.0, vous pouvez stocker jusqu'à 1 Go dans un champ de type text. Dans les anciennes versions, vous étiez limité à la taille maximale d'un bloc (qui, par défaut, valait 8 ko, et au mieux, 32 ko, suivant le choix au moment de la compilation).

Pour utiliser l'interface des grands objets (large object (lo) interface), il est nécessaire de les placer dans un bloc de transaction. Un bloc de transaction commence avec BEGIN et, si la transaction se termine, avec un COMMIT et END. Si la transaction échoue, elle doit être conclue par un ABORT et ROLLBACK.
Exemple 2. Utilisation des objets de grande taille (Large Objects)
<?php $database = pg_connect("dbname=jacarta"); pg_query($database, "begin"); $oid = pg_lo_create($database); echo "$oid\n"; $handle = pg_lo_open($database, $oid, "w"); echo "$handle\n"; pg_lo_write($handle, "large object data"); pg_lo_close($handle); pg_query($database, "commit"); ?>
Vous ne devez pas fermer la connexion au serveur PostgreSQL avant de fermer l'objet de grande taille.

Table des matières
pg_affected_rows -- Retourne le nombre de lignes affectées
pg_cancel_query -- Annule une requête asynchrone
pg_client_encoding -- Lit l'encodage du client
pg_close -- Termine une connexion PostgreSQL
pg_connect -- Établit une connexion PostgreSQL
pg_connection_busy -- Vérifie si la connexion PostgreSQL est occupée
pg_connection_reset -- Relance la connexion au serveur PostgreSQL
pg_connection_status -- Lit le statut de la connexion PostgreSQL
pg_convert -- Convertit des tableaux associatifs en une commande PostgreSQL
pg_copy_from -- Insère des lignes dans une table à partir d'un tableau
pg_copy_to -- Copie une table dans un tableau
pg_dbname -- Retourne le nom de la base de données PostgreSQL
pg_delete -- Efface des lignes PostgreSQL
pg_end_copy -- Synchronise avec le serveur PostgreSQL
pg_escape_bytea -- Protège une chaîne pour insertion dans un champ bytea
pg_escape_string -- Protège une chaîne de caractères pour l'insérer dans un champ texte
pg_execute -- Envoie une requête pour exécuter une requête préparée avec les paramètres donnés et attend le résultat
pg_fetch_all_columns -- Récupère toutes les lignes d'une colonne de résultats particulière en tant que tableau
pg_fetch_all -- Lit toutes les lignes d'un résultat
pg_fetch_array -- Lit une ligne de résultat PostgreSQL dans un tableau
pg_fetch_assoc -- Lit une ligne de résultat PostgreSQL sous forme de tableau numérique
pg_fetch_object -- Lit une ligne de résultat PostgreSQL dans un objet
pg_fetch_result -- Retourne les valeurs d'un résultat
pg_fetch_row -- Lit une ligne dans un tableau
pg_field_is_null -- Teste si un champ PostgreSQL est à NULL
pg_field_name -- Retourne le nom d'un champ PostgreSQL
pg_field_num -- Retourne le numéro d'une colonne
pg_field_prtlen -- Retourne la taille imprimée
pg_field_size -- Retourne la taille interne de stockage d'un champ donné
pg_field_type_oid -- Retourne le type ID (OID) pour le numéro du champ correspondant
pg_field_type -- Retourne le type d'un champ PostgreSQL donné par index
pg_free_result -- Libère la mémoire
pg_get_notify -- Lit le message SQL NOTIFY
pg_get_pid -- Lit l'identifiant de processus du serveur PostgreSQL
pg_get_result -- Lit un résultat PostgreSQL asynchrone
pg_host -- Retourne le nom d'hôte
pg_insert -- Insère un tableau dans une table
pg_last_error -- Lit le dernier message d'erreur sur la connexion
pg_last_notice -- Retourne la dernière note du serveur PostgreSQL
pg_last_oid -- Retourne l'identifiant de la dernière ligne
pg_lo_close -- Ferme un objet de grande taille PostgreSQL
pg_lo_create -- Crée un objet de grande taille PostgreSQL
pg_lo_export -- Exporte un objet de grande taille vers un fichier
pg_lo_import -- Importe un objet de grande taille depuis un fichier
pg_lo_open -- Ouvre un objet de grande taille PostgreSQL
pg_lo_read_all -- Lit un objet de grande taille en totalité
pg_lo_read -- Lit un objet de grande taille
pg_lo_seek -- Modifie la position dans un objet de grande taille
pg_lo_tell -- Retourne la position courante dans un objet de grande taille PostgreSQL
pg_lo_unlink -- Efface un objet de grande taille PostgreSQL
pg_lo_write -- Ecrit un objet de grande taille PostgreSQL
pg_meta_data -- Lit les métadonnées de la table PostgreSQL
pg_num_fields -- Retourne le nombre de champ
pg_num_rows -- Retourne le nombre de lignes PostgreSQL
pg_options -- Retourne les options PostgreSQL
pg_parameter_status -- Consulte un paramètre de configuration courant du serveur
pg_pconnect -- Établit une connexion PostgreSQL persistante
pg_ping -- Ping la connexion à la base
pg_port -- Retourne le numéro de port
pg_prepare -- Envoie une requête pour créer une requête préparée avec les paramètres donnés et attend l'exécution
pg_put_line -- Envoie une chaîne au serveur PostgreSQL
pg_query_params -- Envoie une commande au serveur et attend le résultat, avec les capacités de passer des paramètres séparément de la commande texte SQL
pg_query -- Exécute une requête PostgreSQL
pg_result_error_field -- Retourne un champ individuel d'un rapport d'erreur
pg_result_error -- Lit le message d'erreur associé à un résultat
pg_result_seek -- Modifie la ligne courant dans un résultat
pg_result_status -- Lit le statut du résultat
pg_select -- Effectue une sélection PostgreSQL
pg_send_execute -- Envoie une requête pour exécuter une requête préparée avec des paramètres donnés, sans attendre le(s) résultat(s)
pg_send_prepare -- Envoie une requête pour créer une requête préparée avec les paramètres donnés, sans attendre la fin de son exécution
pg_send_query_params -- Envoie une commande et sépare les paramètres au serveur sans attendre le(s) résultat(s)
pg_send_query -- Exécute une requête PostgreSQL asynchrone
pg_set_client_encoding -- Choisit l'encodage du client PostgreSQL
pg_set_error_verbosity -- Détermine la le degré des messages retournés par pg_last_error() et pg_result_error()
pg_trace -- Active le suivi d'une connexion PostgreSQL
pg_transaction_status -- Retourne le statut de la transaction en cours du serveur
pg_tty -- Retourne le nom de TTY associé à la connexion
pg_unescape_bytea -- Supprime le protection d'une chaîne de type bytea
pg_untrace -- Termine le suivi d'une connexion PostgreSQL
pg_update -- Modifie les lignes d'une table
pg_version -- Retourne un tableau avec les versions du client, du protocole et du serveur (si disponible)

Précédent	Sommaire	Suivant
posix_uname	Niveau supérieur	pg_affected_rows