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 32.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 32.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 32.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 32.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.
PQconnectStartParamsPQconnectStartPQconnectPoll #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 32.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). Notez que
PQsocketPoll cela peut aider à réduire le texte
habituel en faisant abstraction de la configuration de
select(2) ou de poll(2) s'il
est disponible sur votre système. 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_GSS_STARTUP #Négociation du chiffrement GSS.
CONNECTION_CHECK_WRITABLE #Vérification que la connexion est capable de gérer des transactions en écriture.
CONNECTION_CHECK_STANDBY #Vérification que la connexion concerne un serveur secondaire.
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.
PQsocketPoll #
Interroge le descripteur de la socket utilisée par la connexion,
descripteur récupéré avec la fonction PQsocket.
L'usage principal de cette fonction est d'itérer à travers la séquence
de la connexion décrite dans la documentation de
PQconnectStartParams.
typedef pg_int64 pg_usec_time_t;
int PQsocketPoll(int sock, int forRead, int forWrite,
pg_usec_time_t end_time);
Cette fonction interroge un description de fichier, parfois avec un délai
maximal. Si forRead est différent de zéro, la
fonction terminera quand la socket est prête en lecture. Si
forWrite est différent de zéro, la fonction
terminera quand la socket est prête en écriture.
Le délai est spécifié par end_time, qui est le
temps maximal avant d'arrêter l'attente, exprimé en nombre de
microsecondes depuis l'époque Unix (autrement dit, time_t
fois un million). Ce délai est infini si end_time
vaut -1. Ce délai est immédiat (donc non bloquant) si
end_time vaut 0 (ou en fait, tout moment avant
maintenant). Les valeurs du délai peuvent être plus facilement calculées
en ajoutant le nombre de microsecondes souhaité au résultat de la
fonction PQgetCurrentTimeUSec. Notez que les
appels systèmes sous-jacents peuvent être moins précis qu'une
microseconde, donc le délai réel peut être moins précis.
La fonction renvoie une valeur plus grande que 0 si la
condition spécifiée est rencontrée, 0 si le délai est
atteint ou -1 si une erreur est survenue. L'erreur
peut être récupérée en vérifiant la valeur de errno
(3). Au cas où forRead et
forWrite valent zéro, la fonction renvoie
immédiatement l'indication d'un dépassement de délai.
PQsocketPoll est implémenté en utilisant soit
poll(2) soit select(2), suivant
la plateforme. Voir POLLIN et
POLLOUT à partir de poll(2), ou
readfds et writefds à
partir de select(2), pour plus d'informations.
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.
PQresetStartPQresetPoll #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);
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 32.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 32.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, 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 32.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 32.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 32.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,
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 32.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 32.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.)
require_auth #Indique la méthode d'authentification que le client requiert du serveur. Si le serveur n'utilise pas la méthode requise pour authentifier le client ou si l'authentification n'est pas réalisée complètement par le serveur, la connexion échouera. Une liste de méthodes séparée par des virgules peut aussi être fournie. Le serveur utilisera exactement une d'entre elles pour que la connexion réussisse. Par défaut, toute méthode d'authentification est acceptée et le serveur est libre d'ignorer l'authentification.
Il est possible d'indiquer qu'on ne veut pas une méthode en ajoutant
le préfixe ! à cette méthode, auquel cas le serveur
ne doit pas tenter la méthode indiquée ; toute
autre méthode est acceptée et le serveur est libre de ne pas authentifier
le client. Si une liste séparée par des virgules est fournie, le serveur
ne doit tenter aucune de ces méthodes. Les formes
positives et négatives ne peuvent pas être combinées en même temps.
La méthode none requiert que le serveur n'utilise pas
de méthode d'authentification. (Il peut aussi être inversé, pour
réclamer une authentification quelque soit sa forme.)
Les méthodes suivantes peuvent être utilisées :
passwordLe serveur doit demander une authentification par mot de passe en clair.
md5Le serveur doit demander une authentification par mot de passe MD5.
gssLe serveur doit demander une authentification Kerberos via GSSAPI ou établir un canal chiffré avec GSS (voir aussi gssencmode).
sspiLe serveur doit réclamer une authentification SSPI Windows.
scram-sha-256Le serveur doit terminer avec succès une authentification SCRAM-SHA-256 avec le client.
noneLe serveur ne doit pas demander au client une authentification. (Ceci n'empêche pas l'authentification par certificat client via TLS ou l'authentification GSS via son transport sécurisé.)
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.
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 ou --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 19.
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 :
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.
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 :
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 32.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.
sslnegotiation #
Cette option contrôle la négociation du chiffrement SSL si SSL est
utilisé. Dans le mode postgres par défaut, le client
demande tout d'abord au serveur si SSL est accepté. Dans le mode
direct, le client commence l'échange standard SSL
après l'établissement de la connexion TCP/IP. La négociation
traditionnelle du protocole PostgreSQL est
plus flexible avec différentes configurations du serveur. S'il est connu
que le serveur accepte les connexions SSL, le mode
direct nécessite un aller/retour de moins réduisant
la latence de la connexion et permettant aussi l'utilisation d'outils
réseau SSL agnostiques. L'option SSL direct a été ajoutée dans la
version 17 de PostgreSQL.
postgresréalise la négocitation du protocole PostgreSQL protocol. C'est le défaut si l'option n'est pas indiquée.
directlance l'échange SSL directement après l'établissement d'une connexion TCP/IP. C'est seulement autorisé avec sslmode=require ou une configuration supérieure car les configurations inférieures pourraient amener un retour inattendu à l'authentification quand le serveur n'accepte pas l'échange SSL direct.
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ésactivait la compression par défaut, et de nombreux systèmes d'exploitation la désactivaient 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ésactivait 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.
sslcertmode #Cette option détermine si un certificat client peut être envoyer au serveur et si le serveur doit en demander un. Il existe trois modes :
disableUn certificat client n'est jamais envoyé, même s'il est disponible (emplacement par défaut ou fourni via sslcert).
allow (default)Un certificat peut être envoyé si le serveur en réclame un et que le client en possède un.
requireLe serveur doit réclamer un certificat. La connexion échouera si le client n'envoie pas un certificat et le serveur authentifie le client avec succès de toute façon.
sslcertmode=require n'est pas une sécurité
supplémentaire car il n'y a pas de garantie que le serveur valide
correctement le certificat ; les serveurs PostgreSQL réclament
généralement des certificats TLS aux clients qu'ils les valident ou
non. L'option pourrait être utile lors du dépannage de configurations
TLS plus compliquées.
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.
La valeur spéciale system peut être indiquée à la
place, auquel cas les racines du CA de confiance seront chargées. Les
emplacements exacts de ces certificats racines diffèrent parmi les
implémentations et les plateformes SSL. Pour
OpenSSL en particulier, les emplacements
pourraient être encore plus modifiés par les variables d'environnement
SSL_CERT_DIR et SSL_CERT_FILE.
Lors de l'utilisation de sslrootcert=system, le
paramètre sslmode par défaut est changé en
verify-full, et tout paramétrage plus faible
résultera en une erreur. Dans la plupart des cas, il est trivial pour
chacun d'obtenir un certificat dans lequel le système a confiance pour
un nom d'hôte qu'il contrôle, rendant verify-ca et
tous les modes plus faibles inutiles.
La valeur magique system sera privilégiée à un
fichier certificat local de même nom. Si, pour certaines raisons, vous
vous trouvez dans cette situation, utilisez à la place un chemin
alternatif comme sslrootcert=./system.
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,
sauf si le proxy est au courant du protocole d'échange de PostgreSQL,
cela nécessitera de configurer sslnegotiation
à direct.) 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 20.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 20.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.
gssdelegation #
Transférer (déléguer) les informations d'identification GSS au serveur.
La valeur par défaut est 0, ce qui signifie que les
informations ne sont pas transférées au serveur. Configurez-le à 1 pour
qu'elles le soient lorsque c'est possible.
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 32.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-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
load_balance_hosts #Contrôle l'ordre dans lequel le client essaie de se connecter aux hôtes et adresses disponibles. Une fois qu'une tentative réussit, aucun autre hôte ou adresse ne sera testé. Ce paramètre est typiquement utilisé en combinaison avec plusieurs noms d'hôtes ou un enregistement DSN qui renvoit plusieurs IP. Ce paramètre peut être utiliser avec target_session_attrs pour réaliser de la répartition de charge uniquement sur les serveurs secondaires. Une fois connecté avec succès, les requêtes suivants sur cette connexion iront toutes au même serveur. Il existe actuellement deux modes :
disable (par défaut)Aucune répartition de charge n'est réalisée entre hôte. Les hôtes sont essayés dans l'ordre où ils sont fournis et les adresses sont essayées dans l'ordre où elles sont reçues d'un DNS ou d'un fichier hosts.
randomLes hôtes et les adresses sont essayés dans un ordre aléatoire. Cette valeur est principalement utile pour l'ouverture de plusieurs connexions en même temps, possiblement de différentes machines. De cette façon, les connexions seront réparties entre plusieurs serveurs PostgreSQL.
Bien que la répartition aléatoire de charge, à cause de sa nature aléatoire, ne résultera pratiquement jamais en une distribution uniforme, il s'en rapproche statistiquement. Un aspect important ici est que cet algorithme utilise deux niveaux de choix aléatoires. Tout d'abord, les hôtes sont résolus en ordre aléatoire. Puis, avant de résoudre l'hôte suivant, toutes les adresses résolues de lhôte courant seront triées de façon aléatoire. Ce comportement the next host, all resolved addresses for the current host will be tried in random order. Ce comportement peut fausser la quantité de connexions que chaque nœud obtient, et ce grandement dans certains cas, par exemple lorsque certains hôtes résolvent plus d'adresses que d'autres. Mais ce type d'erreur peut également être utilisée à dessein, par exemple pour augmenter le nombre de connexions qu'un serveur plus important obtient en fournissant plusieurs fois son nom d'hôte dans la chaîne.
Lors de l'utilisation de cette valeur, il est recommandé de configurer aussi une valeur raisonnable pour connect_timeout. Parce que, si un des nœuds utilisés par la répartition de charge ne répond pas, un nouveau nœud sera essayé.