Manuel PHP
Précédent |  | Suivant

# C. 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 http://techdocs.postgresql.org/.

# 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
--- | --- | ---
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
pgsql.ignore_notice | "0" | PHP_INI_ALL
pgsql.log_notice | "0" | PHP_INI_ALL

Pour plus de détails sur les constantes PHP_INI_*, reportez-vous à ini_set().

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

pgsql.allow_persistent booléen

  Autorise ou non les connexions persistentes 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 persistentes (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)

`PGSQL_NUM` (entier)

`PGSQL_BOTH` (entier)

`PGSQL_CONNECTION_BAD` (entier)

`PGSQL_CONNECTION_OK` (entier)

`PGSQL_SEEK_SET` (entier)

`PGSQL_SEEK_CUR` (entier)

`PGSQL_SEEK_END` (entier)

`PGSQL_ESCAPE_STRING` (entier)

`PGSQL_ESCAPE_BYTEA` (entier)

`PGSQL_EMPTY_QUERY` (entier)

`PGSQL_COMMAND_OK` (entier)

`PGSQL_TUPLES_OK` (entier)

`PGSQL_COPY_OUT` (entier)

`PGSQL_COPY_IN` (entier)

`PGSQL_BAD_RESPONSE` (entier)

`PGSQL_NONFATAL_ERROR` (entier)

`PGSQL_FATAL_ERROR` (entier)

# 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.

Précédent | Sommaire | Suivant
pfpro_version | Niveau supérieur | pg_affected_rows