PostgreSQLLa base de données la plus sophistiquée au monde.
Documentation PostgreSQL 14.11 » Interfaces client » libpq -- Bibliothèque C » Fonctions de contrôle de connexion à la base de données

34.1. Fonctions de contrôle de connexion à la base de données

Les fonctions suivantes concernent la réalisation d'une connexion avec un serveur PostgreSQL. Un programme peut avoir plusieurs connexions ouvertes sur des serveurs à un même moment (une raison de la faire est d'accéder à plusieurs bases de données). Chaque connexion est représentée par un objet PGconn, obtenu avec la fonction PQconnectdb, PQconnectdbParams ou PQsetdbLogin. Notez que ces fonctions renverront toujours un pointeur d'objet non nul, sauf peut-être dans un cas de manque de mémoire pour l'allocation de l'objet PGconn. La fonction PQstatus doit être appelée pour vérifier le code retour pour une connexion réussie avant de lancer des requêtes via l'objet de connexion.

Avertissement

Si des utilisateurs non dignes de confiance ont accès à une base de données qui n'a pas adopté une méthode sécurisée d'utilisation des schémas, commencez chaque session en supprimant du search_path les schémas accessibles par tout le monde. Il est possible de configurer le paramètre options à la valeur -csearch_path=. Sinon, il est possible d'exécuter PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)") tout de suite après la connexion. Cette considération n'est pas spécifique à la libpq ; elle s'applique à chaque interface permettant d'exécuter des commandes SQL arbitraires.

Avertissement

Sur Unix, la création d'un processus via l'appel système fork() avec des connexions libpq ouvertes peut amener à des résultats imprévisibles car les processus parent et enfants partagent les même sockets et les mêmes ressources du système d'exploitation. Pour cette raison, un tel usage n'est pas recommandé, alors qu'exécuter un exec à partir du processus enfant pour charger un nouvel exécutable est sûr.

PQconnectdbParams

Établit une nouvelle connexion au serveur de base de données.

PGconn *PQconnectdbParams(const char * const *keywords,
                          const char * const *values,
                          int expand_dbname);
       

Cette fonction ouvre une nouvelle connexion à la base de données en utilisant les paramètres à partir des deux tableaux terminés par un NULL. Le premier, keywords, est défini comme un tableau de chaînes, chacune étant un mot-clé. Le second, values, donne la valeur pour chaque mot-clé. Contrairement à PQsetdbLogin ci-dessous, l'ensemble des paramètres peut être étendu sans changer la signature de la fonction donc son utilisation (ou ses versions non bloquantes, à savoir PQconnectStartParams et PQconnectPoll) est recommendée pour les nouvelles applications.

Les mots clés actuellement reconnus sont listés dans Section 34.1.2.

Les tableaux fournis peuvent être vides pour utiliser tous les paramètres par défaut ou peuvent contenir une ou plusieurs configurations. Elles doivent correspondre en longueur. Le traitement s'arrêtera à la première entrée NULL dans le tableau keywords. De plus, si l'entrée values associée à une entrée keywords non NULL est NULL ou une chaîne vide, cette entrée est ignorée et le traitement continue avec la prochaine paire d'entrées des tableaux.

Quand expand_dbname est différent de zéro, la valeur pour le premier mot-clé dbname est testé pour vérifier s'il s'agit d'une chaîne de connexion. Dans ce cas, elle sera « éclatée » dans les paramètres individuels de connexion. La valeur est considérée être une chaîne de connexion, plutôt qu'un nom de base, si elle contient un signe égal (=) ou si elle commence avec un désignateur de schéma URI. (Vous trouverez plus de détails sur les formats de chaîne de connexion dans Section 34.1.1.) Seule la première occurence de dbname est traitée de cette façon ; tout paramètre dbname supplémentaire est traité comme un simple nom de base.

En général, les tableaux de paramètres sont traités du début à la fin. Si un mot clé est répété, la dernière valeur (non NULL ou vide) est utilisée. Cette règle s'applique en particulier quand un mot clé trouvé dans la chaîne de connexion est en conflit avec un mot clé apparaissant dans le tableau keywords. De ce fait, le développeur peut déterminer si les entrées du tableau peuvent surcharger ou être surchargées par des valeurs prises dans la chaîne de connexion. Les entrées du tableau apparaissant avant une entrée dbname éclatée peuvent être surchargées par les champs de la chaîne de connexion et, à leur tour,ces champs peuvent être surchargés par des entrées du tableau apparaissant après dbname (mais, encore une fois, seulement si ces entrées fournissent des valeurs non vides).

Après avoir traité toutes les entrées de tableau et toute chaîne de connexion éclatée, tous les paramètres de connexion restants non configurés sont remplis avec leur valeurs par défaut. Si une variable d'environnement d'un paramètre non configuré (voir Section 34.15) est configuré, sa valeur est utilisée. Si la variable denvironnement n'est pas configurée, alors la valeur par défaut interne du paramètre est utilisée.

PQconnectdb

Établit une nouvelle connexion à un serveur de bases de données.

        PGconn *PQconnectdb(const char *conninfo);
       

Cette fonction ouvre une nouvelle connexion à la base de données en utilisant les paramètres pris à partir de la chaîne conninfo.

La chaîne passée peut être vide pour utiliser tous les paramètres par défaut ou elle peut contenir un ou plusieurs paramètres, séparés par des espaces blancs. Elle peut aussi contenir une URI. Voir Section 34.1.1 pour les détails.

PQsetdbLogin

Crée une nouvelle connexion sur le serveur de bases de données.

PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd);
       

C'est le prédécesseur de PQconnectdb avec un ensemble fixe de paramètres. Cette fonction a les mêmes fonctionnalités sauf que les paramètres manquants seront toujours initialisés avec leur valeurs par défaut. Écrire NULL ou une chaîne vide pour un de ces paramètres fixes dont vous souhaitez utiliser la valeur par défaut.

Si dbName contient un signe = ou a un préfixe URI de connexion valide, il est pris pour une chaîne conninfo exactement de la même façon que si elle était passée à PQconnectdb, et le reste des paramètres est ensuite appliqué comme spécifié dans PQconnectdbParams.

pgtty n'est plus utilisé et toute valeur passée sera ignorée.

PQsetdb

Crée une nouvelle connexion sur le serveur de bases de données.

PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName);
       

C'est une macro faisant appel à PQsetdbLogin avec des pointeurs nuls pour les paramètres login et pwd. Elle est fournie pour la compatibilité avec les très vieux programmes.

PQconnectStartParams
PQconnectStart
PQconnectPoll

Crée une connexion au serveur de bases de données d'une façon non bloquante.

PGconn *PQconnectStartParams(const char * const *keywords,
                             const char * const *values,
                              int expand_dbname);

        PGconn *PQconnectStart(const char *conninfo);

        PostgresPollingStatusType PQconnectPoll(PGconn *conn);
       

Ces trois fonctions sont utilisées pour ouvrir une connexion au serveur de bases de données d'une façon telle que le thread de votre application n'est pas bloqué sur les entrées/sorties distantes en demandant la connexion. Le but de cette approche est que l'attente de la fin des entrées/sorties peut se faire dans la boucle principale de l'application plutôt qu'à l'intérieur de PQconnectdbParams ou PQconnectdb, et donc l'application peut gérer des opérations en parallèle à d'autres activités.

Avec PQconnectStartParams, la connexion à la base de données est faite en utilisant les paramètres à partir des tableaux keywords et values, et contrôlée par expand_dbname, comme décrit dans PQconnectdbParams.

Avec PQconnectStart, la connexion à la base de données est faite en utilisant les paramètres provenant de la chaîne conninfo comme décrit ci-dessus pour PQconnectdb.

Ni PQconnectStartParams ni PQconnectStart ni PQconnectPoll ne bloqueront, aussi longtemps qu'un certain nombre de restrictions est respecté :

  • Le paramètre hostaddr doit être utilisé de façon appropriée pour empêcher l'exécution de requêtes DNS. Voir la documentation de ce paramètre sur Section 34.1.2 pour plus de détails.

  • Si vous appelez PQtrace, assurez-vous que l'objet de flux dans lequel vous enregistrez les traces ne bloquera pas.

  • Assurez-vous que le socket soit dans l'état approprié avant d'appeler PQconnectPoll, comme décrit ci-dessous.

Pour commencer une demande de connexion non bloquante, appelez PQconnectStart ou PQconnectStartParams. Si le résultat est nul, alors libpq a été incapable d'allouer une nouvelle structure PGconn. Sinon, un pointeur valide vers une structure PGconn est renvoyé (bien qu'il ne représente pas encore une connexion valide vers la base de données). Au retour de PQconnectStart, appelez PQstatus(conn). Si le résultat vaut CONNECTION_BAD, la tentative de connexion a déjà échoué, généralement à cause de paramètres de connexion invalides.

Si PQconnectStart ou PQconnectStartParams réussit, la prochaine étape est d'appeler souvent libpq de façon à ce qu'il continue la séquence de connexion. Utilisez PQsocket(conn) pour obtenir le descripteur de socket sous la connexion à la base de données. (Attention, ne supposez pas que la socket reste identique pour les différents appels à PQconnectPoll.) Du coup, une boucle : si le dernier retour de PQconnectPoll(conn) est PGRES_POLLING_READING, attendez que la socket soit prête pour lire (comme indiqué par select(), poll() ou une fonction système similaire). Puis, appelez de nouveau PQconnectPoll(conn). En revanche, si le dernier retour de PQconnectPoll(conn) est PGRES_POLLING_WRITING, attendez que la socket soit prête pour écrire, puis appelez de nouveau PQconnectPoll(conn). À la première itération, si vous avez encore à appeler PQconnectPoll, continuez comme s'il avait renvoyé PGRES_POLLING_WRITING. Continuez cette boucle jusqu'à ce que PQconnectPoll(conn) renvoie PGRES_POLLING_FAILED, indiquant que la procédure de connexion a échoué ou PGRES_POLLING_OK, indiquant le succès de la procédure de connexion.

À tout moment pendant la connexion, le statut de cette connexion peut être vérifié en appelant PQstatus. Si le résultat est CONNECTION_BAD, alors la procédure de connexion a échoué ; si, au contraire, elle renvoie CONNECTION_OK, alors la connexion est prête. Ces deux états sont détectables à partir de la valeur de retour de PQconnectPoll, décrite ci-dessus. D'autres états pourraient survenir lors (et seulement lors) d'une procédure de connexion asynchrone. Ils indiquent l'état actuel de la procédure de connexion et pourraient être utiles pour fournir un retour à l'utilisateur. Ces statuts sont :

CONNECTION_STARTED

Attente de la connexion à réaliser.

CONNECTION_MADE

Connexion OK ; attente d'un envoi.

CONNECTION_AWAITING_RESPONSE

Attente d'une réponse du serveur.

CONNECTION_AUTH_OK

Authentification reçue ; attente de la fin du lancement du moteur.

CONNECTION_SSL_STARTUP

Négociation du cryptage SSL.

CONNECTION_SETENV

Négociation des paramètres de l'environnement.

CONNECTION_CHECK_WRITABLE

Vérification que la connexion est capable de gérer des transactions en écriture.

CONNECTION_CONSUME

En train de traiter les messages de réponse restants sur la connexion.

Notez que, bien que ces constantes resteront (pour maintenir une compatibilité), une application ne devrait jamais se baser sur l'apparition de ces états dans un ordre particulier, ou leur survenance tout court, ou sur le fait que le statut fait partie de ces valeurs documentées. Une application pourrait faire quelque chose comme ça :

switch(PQstatus(conn))
{
    case CONNECTION_STARTED:
        feedback = "Connexion en cours...";
        break;

    case CONNECTION_MADE:
        feedback = "Connecté au serveur...";
        break;
.
.
.
    default:
        feedback = "Connexion...";
}
       

Le paramètre de connexion connect_timeout est ignoré lors de l'utilisation PQconnectPoll ; c'est de la responsabilité de l'application de décider quand une période de temps excessive s'est écoulée. Sinon, PQconnectStart suivi par une boucle PQconnectPoll est équivalent à PQconnectdb.

Notez que quand PQconnectStart ou PQconnectStartParams renvoient un pointeur non NULL, vous devez appeler PQfinish quand vous en avez fini pour libérer la structure et tout bloc mémoire qui y est associé. Ceci doit être fait même si la tentative de connexion échoue ou est abandonnée.

PQconndefaults

Renvoie les options de connexion par défaut.

PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* Mot clé de l'option */
    char   *envvar;    /* Nom de la variable d'environnement équivalente */
    char   *compiled;  /* Valeur par défaut interne */
    char   *val;       /* Valeur actuelle de l'option ou NULL */
    char   *label;     /* Label du champ pour le dialogue de connexion */
    char   *dispchar;  /* Indique comment afficher ce champ
                          dans un dialogue de connexion. Les valeurs sont :
                          ""        Affiche la valeur entrée sans modification
                          "*"       Champ de mot de passe - cache la valeur
                          "D"       Option de débogage - non affiché par défaut
                       */
    int     dispsize;  /* Taille du champ en caractère pour le dialogue */
} PQconninfoOption;
       

Renvoie un tableau d'options de connexion. Ceci pourrait être utilisé pour déterminer toutes les options possibles de PQconnectdb et leur valeurs par défaut. La valeur de retour pointe vers un tableau de structures PQconninfoOption qui se termine avec une entrée utilisant un pointeur nul pour keyword. Le pointeur null est renvoyé si la mémoire n'a pas pu être allouée. Notez que les valeurs par défaut actuelles (champs val) dépendront des variables d'environnement et d'autres contextes. Un fichier de service manquant ou non valide sera ignoré de manière silencieuse. Les demandeurs doivent traiter les données des options de connexion en lecture seule.

Après le traitement du tableau d'options, libérez-le en le passant à la fonction PQconninfoFree. Si cela n'est pas fait, un petit groupe de mémoire est perdu à chaque appel de PQconndefaults.

PQconninfo

Renvoie les options de connexion utilisées par une connexion en cours.

       PQconninfoOption *PQconninfo(PGconn *conn);
       

Renvoie un tableau des options de connexion. Cette fonction peut être utilisée pour déterminer les valeurs de toutes les options de PQconnectdb qui ont été utilisées pour se connecter au serveur. La valeur renvoyée pointe vers un tableau de structures PQconninfoOption qui se termine avec une entrée possédant un pointeur keyword nul. Toutes les notes ci-dessus pour PQconndefaults s'appliquent aussi au résultat de PQconninfo.

PQconninfoParse

Renvoit les options de connexions analysées d'après la chaîne de connexion fournie.

       PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
       

Analyse une chaîne de connexion et renvoie les options résultantes dans un tableau ; renvoit NULL si un problème a été détecté avec la chaîne de connexion. Ceci peut être utilisé pour déterminer les options de PQconnectdb dans la chaîne de connexion fournie. La valeur de retour pointe vers un tableau de structures PQconninfoOption et termine avec une entrée ayant un pointeur keyword nul.

Toutes les options légales seront présentes dans le tableau en résultat mais le PQconninfoOption pour toute option absente de la chaîne de connexion aura sa valeur (val) configurée à NULL ; les valeurs par défaut ne sont pas utilisées.

Si errmsg n'est pas NULL, alors *errmsg est configuré à NULL en cas de succès et sinon à un message d'erreur (alloué via un appel à malloc) expliquant le problèm. (Il est aussi possible pour *errmsg d'être configuré à NULL et la fonction de renvoyer NULL ; cela indique un cas de mémoire épuisée.)

Après avoir traité le tableau des options, libérez-le en le passant à PQconninfoFree. Si ce n'est pas fait, de la mémoire sera perdu à chaque appel à PQconninfoParse. Réciproquement, si une erreur survient et que errmsg n'est pas NULL, assurez-vous de libérer la chaîne d'erreur en utilisant PQfreemem.

PQfinish

Ferme la connexion au serveur. Libère aussi la mémoire utilisée par l'objet PGconn.

void PQfinish(PGconn *conn);
       

Notez que même si la connexion au serveur a échoué (d'après l'indication de PQstatus), l'application devrait appeler PQfinish pour libérer la mémoire utilisée par l'objet PGconn. Le pointeur PGconn ne doit pas être encore utilisé après l'appel à PQfinish.

PQreset

Réinitialise le canal de communication avec le serveur.

void PQreset(PGconn *conn);
       

Cette fonction fermera la connexion au serveur et tentera l'établissement d'une nouvelle connexion au même serveur en utilisant tous les paramètres utilisés précédemment. Ceci pourrait être utile en cas de récupération après une perte de connexion.

PQresetStart
PQresetPoll

Réinitialise le canal de communication avec le serveur d'une façon non bloquante.

       int PQresetStart(PGconn *conn);

       PostgresPollingStatusType PQresetPoll(PGconn *conn);
       

Ces fonctions fermeront la connexion au serveur et tenteront d'établir une nouvelle connexion sur le même serveur, en utilisant tous les paramètres précédemment utilisés. Ceci peut être utile pour revenir à un état normal après une erreur si une connexion est perdue. Ces fonctions diffèrent de PQreset (ci-dessus) dans le fait qu'elles agissent d'une façon non bloquante. Ces fonctions souffrent des mêmes restrictions que PQconnectStartParams, PQconnectStart et PQconnectPoll.

Pour lancer une réinitialisation de la connexion, exécutez PQresetStart. Si cette fonction 0, la réinitialisation a échoué. Si elle renvoie 1, récupérez le résultat de la réinitialisation en utilisant PQresetPoll exactement de la même façon que vous auriez créé la connexion en utilisant PQconnectPoll.

PQpingParams

PQpingParams renvoie le statut du serveur. Elle accepte les mêmes paramètres de connexion que ceux de la fonction PQconnectdbParams, décrite ci-dessus. Néanmoins, il n'est pas nécessaire de fournir les bons nom d'utilisateur, mot de passe, ou nom de base de données pour obtenir le statut du serveur. Néanmoins, si des valeurs incorrectes sont fournies, le serveur tracera une tentative échouée de connexion.

       PGPing PQpingParams(const char * const *keywords,
                    const char * const *values,
                    int expand_dbname);
       

La fonction renvoie une des valeurs suivantes :

PQPING_OK

Le serveur est en cours d'exécution et semble accepter les connexions.

PQPING_REJECT

Le serveur est en cours d'exécution mais est dans un état qui interdit les connexions (démarrage, arrêt, restauration après crash).

PQPING_NO_RESPONSE

Le serveur n'a pas pu être contacté. Cela pourrait indiquer que le serveur n'est pas en cours d'exécution ou qu'il y a un problème avec les paramètres de connexion donnés (par exemple un mauvais numéro de port). Cela peut aussi indiquer un problème de connexion réseau (par exemple un pare-feu qui bloque la demande de connexion).

PQPING_NO_ATTEMPT

Aucune tentative n'a été faite pour contacter le serveur à cause des paramètres fournis erronnés ou à cause d'un problème au niveau client (par exemple un manque mémoire).

PQping

PQping renvoie l'état du serveur. Elle accepte les mêmes paramètres de connexion que ceux de la fonction PQconnectdb, décrite ci-dessus. Néanmoins, il n'est pas nécessaire de fournir les bons nom d'utilisateur, mot de passe, ou nom de base de données pour obtenir le statut du serveur; toutefois, si des valeurs incorrectes sont fournies, le serveur tracera une tentative de connexion en échec.

       PGPing PQping(const char *conninfo);
       

Les valeurs de retour sont les mêmes que pour PQpingParams.

PQsetSSLKeyPassHook_OpenSSL

PQsetSSLKeyPassHook_OpenSSL permet à une application de passer outre la gestion par défaut des fichiers clés de certificats client de la libpq en utilisant sslpassword ou une invite interactive.

void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);
       

L'application passe un pointeur a une fonction callback avec la signature :

int callback_fn(char *buf, int size, PGconn *conn);
       

que libpq appelera à la place du gestionnaire de la fonction par défaut PQdefaultSSLKeyPassHook_OpenSSL. Le callback devra déterminer le mot de passe pour la clé et la copier dans le résultat tampon buf de taille size. La chaîne dans buf doit être terminée par null. Le callback doit retourner la longueur du mot de passe stockée dans buf en excluant le caractère terminateur nul. En cas d'échec, le callback devra affecter buf[0] = '\0' et retourner 0. Voir PQdefaultSSLKeyPassHook_OpenSSL dans le code source de libpq pour un exemple.

Si l'utilisateur spécifie un emplacement explicite de la clef, son chemin sera dans conn->sslkey quand le callback est appelé. Il sera vide si le chemin de clé par défaut est utilisé. Pour les clés qui sont spécifiques au moteur, celui-ci est responsable de leurs implémentations qu'elles utilisent le callback mot de passe OpenSSL ou qu'elles définissent leur propre gestionnaire.

Le callback de l'application peut choisir de déléguer les cas non gérés à PQdefaultSSLKeyPassHook_OpenSSL, ou l'appeler en premier et essayer autre chose si elle retourne 0, ou complétement la passer outre.

Le callback ne doit pas éviter le contrôle de flux normal avec quelques exceptions, longjmp(...), etc. Il doit retourner normallement.

PQgetSSLKeyPassHook_OpenSSL

PQgetSSLKeyPassHook_OpenSSL retourne le point d'ancrage de la fonction de mot de passe de clé de certificat client courant, ou NULL si aucun n'a été affecté.

PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
       

34.1.1. Chaînes de connexion

Plusieurs fonctions de la bibliothèque libpq analysent une chaîne donnée par l'utilisateur pour obtenir les paramètres de connexion. Deux formats sont acceptés pour ces chaînes : les chaînes mot clé/valeur et les URI. Les URI respectent généralement la RFC 3986, sauf que les chaînes de connexions multi hôtes sont autorisées, comme décrit ci-dessous.

34.1.1.1. Chaînes de connexion clé/valeur

Dans le format mot clé/valeur, chaque configuration de paramètre se présente sous la forme mot clé = valeur avec des espaces entre les paramètres. Les espaces autour du signe égal sont optionnels. Pour écrire une valeur vide ou une valeur contenant des espaces, il est nécessaires de l'entourer de guillemets simples, par exemple clé = 'une valeur'. Les guillemets simples et les antislashs compris dans une valeur doivent être échappés par un antislash, comme ceci \' et ceci \\.

Exemple :

      host=localhost port=5432 dbname=mabase connect_timeout=10
     

Les mots clés reconnus pour les paramètres sont listés dans Section 34.1.2.

34.1.1.2. URI de connexion

La forme générale pour une URI de connexion est :

      postgresql://[utilisateur[:mot_de_passe]@][hote][:port][,...][/nom_base][?param1=valeur1&...]
      postgresql://[spec_utilisateur@][spec_hote][/nom_base][?spec_param]

spec_utilisateur vaut :

utilisateur[:motdepasse]

et spec_hote vaut :

[hote][:port][,...]

et spec_param vaut :

nom=valeur[&...]
     

Le désignateur d'URI peut être soit postgresql:// soit postgres://. Chacune des parties restantes de l'URI est optionnelle. Les exemples suivants montrent des syntaxes valides pour l'URI :

 postgresql://
 postgresql://localhost
 postgresql://localhost:5433
 postgresql://localhost/ma_base
 postgresql://utilisateur@localhost
 postgresql://utilisateur:secret@localhost
 postgresql://autre@localhost/autre_base?connect_timeout=10&application_name=mon_appli
 postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp
     

Les valeurs qui apparaitraient normalement dans la partie hiérarchique de l'URI peuvent être aussi données sous la forme de paramètres nommés. Par exemple :

 postgresql:///ma_base?host=localhost&port=5433
     

Tous les paramètres nommés doivent correspondre aux mots clés listés dans Section 34.1.2, sauf que, pour la compatibilité avec les URI des connexions JDBC, les parties avec of ssl=true sont traduites en sslmode=require.

L'URI de connexion doit être encodée avec percent-encoding si elle inclut des symboles avec des significations spéciales dans toutes les parties. Voici un exemple où un signe égal (=) est remplacé avec %3D et un caractère espace avec %20 :

postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
     

La partie host peut être soit un nom d'hôte soit une adresse IP. Pour indiquer une adresse IPv6, il est nécessaire de l'englober dans des crochets :

      postgresql://[2001:db8::1234]/database
     

La partie host est interprétée de la façon décrite pour le paramètre host. En particulier, une connexion par socket de domaine Unix est choisi si la partie host est vide ou ressemble à un nom de chemin absolu. Dans tous les autres cas, une connexion TCP/IP est démarrée. Cependant, notez que le slash est un caractère réservé dans la partie hiérarchique de l'URI. Donc, pour indiquer un répertoire non standard pour la socket de domaine Unix, il faut soit omettre d'indiquer la partie host dans l'URI et l'indiquer en tant que paramètre nommé, soit encoder le chemin dans le composant host de l'URI :

 postgresql:///dbname?host=/var/lib/postgresql
 postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
     

Il est possible de spécifier plusieurs composants hôte, chacun avec un port optionnel, dans une seule URI. Une URI de la forme postgresql://host1:port1,host2:port2,host3:port3/ est équivalent à une chaîne de connexion de la forme host=host1,host2,host3 port=port1,port2,port3. Comme indiqué plus en détails plus bas, chaque hôte sera testé à son tour jusqu'à ce qu'une connexion soit établie avec succès.

34.1.1.3. Spécifier plusieurs hôtes

Il est possible de spécifier plusieurs hôtes où se connecter. Ils sont essayés dans l'ordre donné. Dans un format clé/valeur, les options host, hostaddr, and port acceptent des listes de valeurs séparées par une virgule. Le même nombre d'éléments doit être donné dans chaque option qui est spécifiée pour que le premier élément dans hostaddr au premier nom d'hôte, le second hostaddr correspond au second nom d'hôte, et ainsi de suite. Seule exception pour l'option port, si un seul port est spécifié, il est utilisé pour tous les hôtes.

Dans le format de connexion URI, vous pouvez lister plusieurs paires hote:port séparées par des virgules dans le composant host de l'URI.

Quelque soit le format, un simple nom d'hôte peut aussi se traduire en plusieurs adresses réseau. Un exemple habituel est un hôte qui a à la fois une adresse IPv4 et une adresse IPv6.

Quand plusieurs hôtes sont indiqués ou quand un nom d'hôte est converti en plusieurs adresses, tous les hôtes et adresses seront essayés dans l'ordre jusqu'à ce qu'une connexion réussisse. Si aucun des hôtes ne peut être atteint, la connexion échoue. Si la connexion réussit mais que l'authentification échoue, les autres hôtes de la liste ne seront pas testés.

Si un fichier de mots de passe est utilisé, vous pouvez avoir plusieurs mots de passe pour des hôtes différents. Toutes les autres options de connexion sont identiques pour chaque hôte de la liste. Par exemple, il n'est pas possible d'indiquer un nom d'utilisateur différent pour les différents hôtes.

34.1.2. Mots clés de la chaîne de connexion

Les mots clés actuellement reconnus sont :

host

Nom de l'hôte où se connecter. Si un nom d'hôte ressemble à un nom de chemin absolu, il spécifie une communication par domaine Unix plutôt qu'une communication TCP/IP ; la valeur est le nom du répertoire où le fichier socket est stocké. (Sur Unix, un chemin absolu commence par un slash. Sur windows, les chemins débutant par la lettre du lecteur sont aussi reconnus.) Si le nom de l'ĥote commence avec un @, il est pris pour un socket de domaine Unix dans l'espace de nom abstrait (actuellement supporté sur Linux et Windows). Par défaut, quand host n'est pas spécifié ou est vide, il s'agit d'une communication par socket de domaine Unix dans /tmp (ou tout autre répertoire de socket spécifié lors de la construction de PostgreSQL). Sur Windows et sur les machines sans socket de domaine Unix, la valeur par défaut est de se connecter à localhost.

Une liste de noms d'hôtes séparés par des virgules est aussi acceptée, auquel cas chaque nom d'hôte est testé dans l'ordre ; un élément vide dans la liste implique le comportement par défaut comme décrit plus haut. Voir Section 34.1.1.3 pour les détails.

hostaddr

Adresse IP numérique de l'hôte de connexion. Elle devrait être au format d'adresse standard IPv4, par exemple 172.28.40.9. Si votre machine supporte IPv6, vous pouvez aussi utiliser ces adresses. La communication TCP/IP est toujours utilisée lorsqu'une chaîne non vide est spécifiée pour ce paramètre. Si ce paramètre n'est pas spécifié, la valeur pour host sera résolue pour trouver l'adresse IP correspondante -- ou, si host spécifie une adresse IP, cette valeur sera utilisée directement.

Utiliser hostaddr permet à l'application d'éviter une résolution de nom, ce qui pourrait être important dans les applications avec des contraintes de temps. Cependant, un nom d'hôte est requis pour les méthodes d'authentification GSSAPI ou SSPI, ainsi que pour la vérification de certificat SSL en verify-full. Les règles suivantes sont observées :

  • Si host est indiqué sans hostaddr, une résolution du nom de l'hôte est lancée. (Si vous utilisez PQconnectPoll, la recherche survient quand PQconnectPoll considère le nom d'hôte pour la première fois, et cela pourrait être la cause d'un blocage de PQconnectPoll pendant une bonne durée de temps.)

  • Si hostaddr est indiqué sans host, la valeur de hostaddr fournit l'adresse réseau de l'hôte. La tentative de connexion échouera si la méthode d'authentification nécessite un nom d'hôte.

  • Si host et hostaddr sont spécifiés, la valeur de hostaddr donne l'adresse réseau de l'hôte. La valeur de host est ignorée sauf si la méthode d'authentification la réclame, auquel cas elle sera utilisée comme nom d'hôte.

Notez que l'authentification a de grandes chances d'échouer si host n'est pas le nom du serveur à l'adresse réseau hostaddr. Et quand host et hostaddr sont tous deux spécifiés, seul host est utilisé pour identifier la connexion dans un fichier de mots de passe (voir la Section 34.16).

Une liste d'adresses hostaddr séparées par des virgules est aussi acceptée, auquel cas chaque hôte est essayé dans cet ordre. Un élément vide dans la liste mène à l'utilisation du nom d'hôte correspondant, ou, s'il est vide aussi, de la valeur par défaut. Voir Section 34.1.1.3 pour plus de détails.

Sans un nom ou une adresse d'hôte, libpq se connectera en utilisant un socket local de domaine Unix. Sur Windows et sur des machines sans sockets de domaine Unix, il tentera une connexion sur localhost.

port

Numéro de port pour la connexion au serveur ou extension du nom de fichier pour des connexions de domaine Unix. Si plusieurs hôtes sont indiquées dans les paramètres host ou hostaddr, ce paramètre spécifie une liste de ports séparés par des virgules et de même taille que la liste des hôtes, ou bien il peut préciser un seul port à tester pour tous les hôtes. Une chaîne vide, ou un élément vide de la liste, indique le numéro de port par défaut établi à la compilation de PostgreSQL.

dbname

Nom de la base de données. Par défaut, la même que le nom utilisateur. Dans certains contextes, la valeur est vérifiée pour les formats étendus ; voir Section 34.1.1 pour plus d'informations.

user

Nom de l'utilisateur PostgreSQL qui se connecte. Par défaut, il s'agit du même nom que l'utilisateur système lançant l'application.

password

Mot de passe à utiliser si le serveur demande une authentification par mot de passe.

passfile

Spécifie le nom du fichier utilisé pour stocker les mots de passe (voir Section 34.16). La valeur par défaut est ~/.pgpass, ou %APPDATA%\postgresql\pgpass.conf sur Microsoft Windows. (Aucune erreur n'est levée si le fichier n'existe pas.)

channel_binding

Cette option contrôle l'utilisation cliente de la liaison de canal. Une valeur require signifie que la connexion doit toujours employer la liaison de canal, prefer signifie que le client doit choisir la liaison de canal si disponible, et disable empêche l'utilisation de liaison de canal. Le défaut est prefer si PostgreSQL est compilé avec le support SSL.

La liaison de canal est une méthode permettant au serveur de s'authentifier vers un client. Elle est seulement supportée sur des connexions SSL avec PostgreSQL 11 ou des versions ultérieures utilisant la méthode d'authentification SCRAM.

connect_timeout

Temps d'attente maximum lors d'une connexion, en secondes (écrit sous la forme d'un entier décimal, par exemple 10). La valeur zéro, une valeur négative ou sans valeur indique une attente infinie. Le délai minimal autorisé est 2 secondes, de ce fait la valeur 1 est interprétée comme 2. Ce délai s'applique séparément pour chaque nom d'hôte ou adresse IP. Par exemple, si vous indiquez deux hôtes et que le paramètre connect_timeout vaut 5, chaque hôte sera en timeout si aucune connexion n'est réalisée en 5 secondes, donc le temps total passé à attendre une connexion peut monter jusqu'à 10 secondes.

client_encoding

Ceci configure le paramètre client_encoding pour cette connexion. En plus des valeurs acceptées par l'option correspondante du serveur, vous pouvez utiliser auto pour déterminer le bon encodage à partir de la locale courante du client (variable d'environnement LC_CTYPE sur les systèmes Unix).

options

Spécifie les options en ligne de commande à envoyer au serveur à l'exécution. Par exemple, en le configurant à -c geqo=off, cela configure la valeur de la session pour le paramètre geqo à off. Les espaces à l'intérieur de cette chaîne sont considérés comme séparateurs d'arguments, sauf si ils sont échappés avec le caractère d'échappement \ ; écrivez \\ pour obtenir le caractère d'échappement lui-même. Pour une discussion détaillée des options disponibles, voir Chapitre 20.

application_name

Précise une valeur pour le paramètre de configuration application_name.

fallback_application_name

Indique une valeur de secours pour le paramètre de configuration application_name. Cette valeur sera utilisée si aucune valeur n'est donnée à application_name via un paramètre de connexion ou la variable d'environnement PGAPPNAME. L'indication d'un nom de secours est utile pour les programmes outils génériques qui souhaitent configurer un nom d'application par défaut mais permettent sa surcharge par l'utilisateur.

keepalives

Contrôle si les paramètres TCP keepalives côté client sont utilisés. La valeur par défaut est de 1, signifiant ainsi qu'ils sont utilisés. Vous pouvez le configurer à 0, ce qui aura pour effet de les désactiver si vous n'en voulez pas. Ce paramètre est ignoré pour les connexions réalisées via un socket de domaine Unix.

keepalives_idle

Contrôle le nombre de secondes d'inactivité après lequel TCP doit envoyer un message keepalive au server. Une valeur de zéro utilise la valeur par défaut du système. Ce paramètre est ignoré pour les connexions réalisées via un socket de domaine Unix ou si les paramètres keepalives sont désactivés. Ce paramètre est uniquement supporté sur les systèmes où les options TCP_KEEPIDLE ou une option socket équivalente sont disponibles et sur Windows ; pour les autres systèmes, ce paramètre n'a pas d'effet.

keepalives_interval

Contrôle le nombre de secondes après lequel un message TCP keepalive doit être retransmis si le serveur ne l'a pas acquitté. Une valeur de zéro utilise la valeur par défaut du système. Ce paramètre est uniquement supporté sur les systèmes où l'option TCP_KEEPINTVL ou une option socket équivalente est disponible et sur Windows ; pour les autres systèmes, ce paramètre n'a pas d'effet.

keepalives_count

Contrôle le nombre de messages TCP keepalive pouvant être perdus avant que la connexion du client au serveur ne soit considérée comme perdue. Une valeur de zéro utilise la valeur par défaut du système. Ce paramètre est uniquement supporté sur les systèmes où l'option TCP_KEEPCNT ou une option socket équivalente est disponible et sur Windows ; pour les autres systèmes, ce paramètre n'a pas d'effet.

tcp_user_timeout

Contrôle le nombre de millisecondes durant lesquelles les données transmises peuvent rester non acquittées avant que la connexion soit fermée de force. Une valeur à zéro indique d'utiliser la valeur par défaut du système. Ce paramètre est ignoré pour les connexions initiées via socket de domaine Unix. Il est seulement pris en charge sur les systèmes où TCP_USER_TIMEOUT est disponible ; sur les autres systèmes, il n'a pas d'effet.

replication

Cette option détermine si la connexion doit utiliser le protocole de réplication au lieu du protocole normal. C'est ce qu'utilisent les connexions de réplication de PostgreSQL, ainsi que des outils comme pg_basebackup, mais il peut aussi être utilisé par des applications tierces. Pour une description du protocole de réplication, consulter Section 53.4

Les valeurs suivantes, non sensibles à la casse, sont supportées :

true, on, yes, 1

La connexion passe en mode réplication physique.

database

La connexion passe en mode réplication logique, se connectant à la base spécifiée par le paramètre dbname.

false, off, no, 0

On utilise la connexion habituelle, ce qui est le comportement par défaut.

En mode réplication physique ou logique, seul le protocole simple peut être utilisé.

gssencmode

Cette option détermine si une connexion TCP/IP sécurisée avec GSS sera négociée avec le serveur, et si oui avec quelle priorité. Il y a trois modes :

disable

essaie uniquement une connexion non chiffrée avec GSSAPI.

prefer (par défaut)

si des informations d'authentification GSSAPI sont présentes (c'est-à-dire, dans un cache d'authentification), essaie d'abord une connexion chiffrée avec GSSAPI ; si elle échoue ou qu'il n'y a pas les informations d'authentification, essaie une connexion non chiffrée avec GSSAPI. C'est le comportement par défaut quand PostgreSQL a été compilé avec le support de GSSAPI.

require

essaie uniquement une connexion chiffrée avec GSSAPI.

gssencmode est ignoré pour les connexions par socket du domaine Unix. Si PostgreSQL est compilé sans le support de GSSAPI, l'utilisation de l'option require provoquera une erreur, alors que prefer sera acceptée mais, dans ce cas, libpq n'essaiera pas d'initier une connexion chiffrée avec GSSAPI.

sslmode

Cette option détermine si ou avec quelle priorité une connexion TCP/IP SSL sécurisée sera négociée avec le serveur. Il existe six modes :

disable

essaie seulement une connexion non SSL

allow

essaie en premier lieu une connexion non SSL ; si cette tentative échoue, essaie une connexion SSL

prefer (par défaut)

essaie en premier lieu une connexion SSL ; si cette tentative échoue, essaie une connexion non SSL

require

essaie seulement une connexion SSL. Si un certificat racine d'autorité (CA) est présent, vérifie le certificat de la même façon que si verify-ca était spécifié

verify-ca

essaie seulement une connexion SSL et vérifie que le certificat client est créé par une autorité de certification (CA) de confiance

verify-full

essaie seulement une connexion SSL, vérifie que le certificat client est créé par un CA de confiance et que le nom du serveur correspond bien à celui du certificat

Voir Section 34.19 pour une description détaillée du fonctionnement de ces options.

sslmode est ignoré pour la communication par socket de domaine Unix. Si PostgreSQL est compilé sans le support de SSL, l'utilisation des options require, verify-ca et verify-full causera une erreur, alors que les options allow et prefer seront acceptées, bien qu'en fait libpq n'essaiera pas de négocier une connexion SSL.

Notez que si le chiffrement GSSAPI est possible, il sera utilisé de préférence au chiffrement SSL, quelque soit la valeur de sslmode. Pour forcer l'utilisation du chiffrement SSL dans un environnement qui dispose d'une infrastructure GSSAPI fonctionnelle (tel qu'un serveur Kerberos), configurez aussi gssencmode à disable.

requiressl

Cette option est obsolète et remplacée par l'option sslmode.

Si initialisée à 1, une connexion SSL au serveur est requise (ce qui est équivalent à un sslmode require). libpq refusera alors de se connecter si le serveur n'accepte pas une connexion SSL. Si initialisée à 0 (la valeur par défaut), libpq négociera le type de connexion avec le serveur (équivalent à un sslmode prefer). Cette option est seulement disponible si PostgreSQL est compilé avec le support SSL.

sslcompression

Si ce paramètre vaut 1, les données envoyées sur des connexions SSL seront compressées. S'il vaut 0, la compression sera désactivée. Le défaut est 0. Ce paramètre est ignoré pour une connexion sans SSL.

De nos jours, la compression SSL est considérée non sûre et son usage n'est plus recommandé. OpenSSL 1.1.0 désactive la compression par défaut, et de nombreux systèmes d'exploitation la désactive aussi dans des versions précédentes, donc activer ce paramètre n'aura aucun effet si le serveur n'accepte pas la compression. PostgreSQL 14 désactive totalement la compression dans le moteur.

Si la sécurité n'est pas un souci majeur, la compression peut améliorer le débit si le réseau est le goulot d'étranglement. Désactiver la compression peut améliorer le temps de réponse et le débit si le processeur est le facteur limitant.

sslcert

Ce paramètre indique le nom du fichier du certificat SSL client, remplaçant le fichier par défaut, ~/.postgresql/postgresql.crt. Ce paramètre est ignoré si la connexion n'utilise pas SSL.

sslkey

Ce paramètre indique l'emplacement de la clé secrète utilisée pour le certificat client. Il peut soit indiquer un nom de fichier qui sera utilisé à la place du fichier ~/.postgresql/postgresql.key par défaut, soit indiquer une clé obtenue par un « moteur » externe (les moteurs sont des modules chargeables d'OpenSSL). La spécification d'un moteur externe devrait consister en un nom de moteur et un identifiant de clé spécifique au moteur, les deux séparés par une virgule. Ce paramètre est ignoré si la connexion n'utilise pas SSL.

sslpassword

Ce paramètre définit le mot de passe pour la clé secrète spécifiée dans sslkey, permettant aux clés de certificat privé du client d'être stockées sous format chiffré sur disque même quand la saisie interactive de passphrase n'est pas pratique.

Spécifier ce paramètre avec toute valeur non vide supprime l'invite de saisie Enter PEM pass phrase: que OpenSSL émet par défaut quand une clé de certificat client chiffrée est fournie à libpq.

Si la clé est non chiffrée, ce paramètre est ignoré. Le paramètre n'a pas d'effet sur les clés spécifiée par les moteurs OpenSSL à moins que le moteur utilise le mécanisme de callback de mot de passe OpenSSL pour les invites de saisie.

Il n'y a pas de variable d'environment équivalente pour cette option, et aucune possibilité pour la déterminer dans .pgpass. Elle peut être utilisée dans un fichier de service de définition de connexion. Les utilisateurs avec des usages plus sophistiqués devraient considérer l'utilisation des moteurs OpenSSL et outils comme PKCS#11 ou les périphériques de déchargement de crypto USB.

sslrootcert

Ce paramètre indique le nom d'un fichier contenant le ou les certificats de l'autorité de certification SSL (CA). Si le fichier existe, le certificat du serveur sera vérifié. La signature devra appartenir à une de ces autorités. La valeur par défaut est ~/.postgresql/root.crt.

sslcrl

Ce paramètre indique le nom du fichier de la liste de révocation du certificat SSL serveur. Les certificats listés dans ce fichier, s'il existe, seront rejetés lors d'une tentative d'authentification avec le certificat du serveur. Si ni sslcrl ni sslcrldir ne sont configurés, ce paramètre est pris pour ~/.postgresql/root.crl.

sslcrldir

Ce paramètre indique le nom du répertoire de la liste de révocation des certificats SSL serveurs (CRL). Les certificats listés dans les fichiers de ce répertoire, s'il existe, seront rejetés lors de tentative d'authentification du certificat du serveur.

Le répertoire doit être préparé avec la commande OpenSSL openssl rehash ou c_rehash. Voir sa documentation pour les détails.

sslcrl et sslcrldir peuvent être indiqués ensemble.

sslsni

Si ce paramètre est configuré à A (sa valeur par défaut), libpq configure l'extension TLS « Server Name Indication » (SNI) sur les connexions SSL. En configurant ce paramètre à 0, il est désactivé.

Server Name Indication peut être utilisé par les proxies SSL pour router les connexions sans avoir à déchiffrer le flux SSL. (Notez que cela requiert un proxy comprenant le système de handshake du protocole PostgreSQL, pas n'importe quel proxy SSL.) Néanmoins, SNI fait que le nom d'hôte de destination apparaît en clair sur le trafic réseau, donc il pourrait être indésirable dans certains cas.

requirepeer

Ce paramètre indique le nom d'utilisateur du serveur auprès du système d'exploitation, par exemple requirepeer=postgres. Lors d'une connexion par socket de domaine Unix, si ce paramètre est configuré, le client vérifie au début de la connexion que le processus tourne sous le nom d'utilisateur indiqué ; dans le cas contraire, la connexion échoue avec une erreur. Ce paramètre peut être utilisé pour fournir une authentification serveur similaire à celle disponible pour les certificats SSL avec les connexions TCP/IP. (Notez que, si la socket de domaine Unix est dans /tmp ou tout espace autorisé en écriture pour tout le monde, n'importe quel utilisateur peut y mettre un serveur en écoute. Utilisez ce paramètre pour vous assurer que vous êtes connecté à un serveur exécuté par un utilisateur de confiance.) Cette option est seulement supportée par les plateformes où la méthode d'authentification peer est disponible ; voir Section 21.9.

ssl_min_protocol_version

Ce paramètre spécifie la version minimale de protocole SSL/TLS pour permettre la connexion. Les valeurs valides sont TLSv1, TLSv1.1, TLSv1.2 et TLSv1.3. Les protocoles supportés dépendent de la version utilisée de OpenSSL, les plus anciennes versions ne supportant pas les versions de protocole les plus modernes. S'il n'est pas indiqué, la valeur par défaut TLSv1.2, ce qui satisfait les bonnes pratiques de l'industrie lors de l'écriture de ce document.

ssl_max_protocol_version

Ce paramètre spécifie la version maximale de protocole SSL/TLS pour permettre la connexion. Les valeurs valides sont TLSv1, TLSv1.1, TLSv1.2 et TLSv1.3. Les protocoles supportés dépendent de la version utilisée de OpenSSL, les anciennes versions ne supportant pas les versions les plus modernes du protocole. S'il n'est pas affecté, ce paramètre est ignoré et la connexion utilisera la version maximale du protocole définie par le backend, si elle existe. Affecter une version maximale du protocole est principalement utile pour tester ou si certains composants ont des problèmes à utiliser un protocole plus récent.

krbsrvname

Nom du service Kerberos à utiliser lors de l'authentification avec GSSAPI. Il doit correspondre avec le nom du service spécifié dans la configuration du serveur pour que l'authentification Kerberos puisse réussir. (Voir aussi la Section 21.6.) La valeur par défaut est normalement postgres, mais cela peut être changé lors de la compilation de PostgreSQL avec l'option --with-krb-srvnam de configure. Dans la plupart des environnements, ce paramètre n'a jamais besoin d'être modifié. Certaines implémentations Kerberos nécessitent un nom de service différent, par exemple Microsoft Active Directory qui réclame que le nom de service soit en majuscules (POSTGRES).

gsslib

Bibliothèque GSS à utiliser pour l'authentification GSSAPI. Ce paramètre est actuellement ignoré, sauf sur les versions Windows qui incluent la prise en charge de GSSAPI et de SSPI. Dans ce cas, configurer ce paramètre à gssapi pour amener la libpq à utiliser la bibliothèque GSSAPI pour l'authentification au lieu de SSPI par défaut.

service

Nom du service à utiliser pour des paramètres supplémentaires. Il spécifie un nom de service dans pg_service.conf contenant des paramètres de connexion supplémentaires. Ceci permet aux applications de spécifier uniquement un nom de service pour que les paramètres de connexion puissent être maintenus de façon centralisée. Voir Section 34.17.

target_session_attrs

Cette option détermine si la session doit avoir certaines propriétés pour être acceptable. C'est typiquement utilisé en combinaison avec plusieurs noms d'hôte pour sélectionner la première alternative acceptable parmi différents hôtes. Il existe six modes :

any (default)

toute connexion réussie est acceptable

read-write

la session doit accepter les transactions en lecture/écriture par défaut (c'est-à-dire que le serveur ne doit pas être en mode hot standby et le paramètre default_transaction_read_only doit être à off)

read-only

la session ne doit pas accepter les transactions en lecture/écriture par défaut (l'inverse)

primary

le serveur ne doit pas être en mode hot standby

standby

le serveur doit être en mode hot standby

prefer-standby

essaie tout d'abord de trouver un serveur secondaire, mais aucun des hôtes listés n'est un serveur secondaire, alors tente de nouveau dans le mode any