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.
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( 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.
conn, "SELECT
pg_catalog.set_config('search_path', '', false)")
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.
PQsetdbLoginCré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.
PQsetdbCré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.
PQconnectStartParamsPQconnectStartPQconnectPollCré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_STARTEDAttente de la connexion à réaliser.
CONNECTION_MADEConnexion OK ; attente d'un envoi.
CONNECTION_AWAITING_RESPONSEAttente d'une réponse du serveur.
CONNECTION_AUTH_OKAuthentification reçue ; attente de la fin du lancement du moteur.
CONNECTION_SSL_STARTUPNégociation du cryptage SSL.
CONNECTION_SETENVNégociation des paramètres de l'environnement.
CONNECTION_CHECK_WRITABLEVérification que la connexion est capable de gérer des transactions en écriture.
CONNECTION_CONSUMEEn 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.
PQconndefaultsRenvoie 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.
PQconninfoRenvoie 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.
PQconninfoParseRenvoit 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.
PQresetRé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.
PQresetStartPQresetPollRé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_OKLe serveur est en cours d'exécution et semble accepter les connexions.
PQPING_REJECTLe 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_RESPONSELe 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_ATTEMPTAucune 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);
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.
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.
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]
où 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.
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.
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.
dbnameNom 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.
userNom 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.
passwordMot 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_namePré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.
keepalivesContrô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.
replicationCette 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é.
gssencmodeCette 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 :
disableessaie 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.
requireessaie 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.
sslmodeCette 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 :
disableessaie seulement une connexion non SSL
allowessaie 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-caessaie seulement une connexion SSL et vérifie que le certificat client est créé par une autorité de certification (CA) de confiance
verify-fullessaie 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.
sslcompressionSi 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.
sslcrldirCe 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.
sslsniSi 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_attrsCette 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-onlyla session ne doit pas accepter les transactions en lecture/écriture par défaut (l'inverse)
primaryle serveur ne doit pas être en mode hot standby
standbyle 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