Configuration : pgbouncer.ini

Fichier de configuration PgBouncer (pgbouncer.ini) – Référence

Référence

Description

Le fichier de configuration est au format « ini ». Les noms de section sont entre [ et ]. Les lignes commençant par ; ou # sont traitées comme des commentaires et ignorées. Les caractères ; et # ne sont pas reconnus comme spéciaux lorsqu’ils apparaissent ultérieurement dans la ligne.

Paramètres génériques

fichier_journal

Spécifie le fichier de journalisation. En mode démon (-d), il faut définir soit ce paramètre, soit syslog.

Le fichier journal reste ouvert, de sorte que, après rotation, il faut exécuter kill -HUP ou depuis la console RELOAD;. Sur Windows, le service doit être arrêté puis redémarré.

Notez que la configuration de logfile ne désactive pas en elle-même la journalisation vers stderr. Utilisez l’option en ligne de commande -q ou -d à cette fin.

Par défaut : non défini

fichier_pid

Spécifie le fichier PID. Sans pidfile défini, la démonisation (-d) n’est pas autorisée.

Par défaut : non défini

écoute_adresse

Spécifie une liste (séparée par des virgules) d’adresses sur lesquelles écouter les connexions TCP. Vous pouvez également utiliser *, ce qui signifie « écouter sur toutes les adresses ». Si ce paramètre n’est pas défini, seules les connexions via socket Unix sont acceptées.

Les adresses peuvent être spécifiées sous forme numérique (IPv4/IPv6) ou par nom.

Par défaut : non défini

port_ecoute

Port sur lequel écouter. S’applique aux sockets TCP et Unix.

Par défaut : 6432

répertoire_socket_unix

Spécifie l’emplacement des sockets Unix. S’applique à la fois au socket d’écoute et aux connexions vers le serveur. Si la valeur est une chaîne vide, les sockets Unix sont désactivés. Une valeur commençant par @ indique qu’un socket Unix dans l’espace de noms abstrait doit être créé (actuellement pris en charge sous Linux et Windows).

Pour permettre le redémarrage en ligne (-R), une socket Unix doit être configurée et être située dans l’espace de noms du système de fichiers.

Par défaut : /tmp (vide sous Windows)

mode_socket_unix

Mode système de fichiers pour les sockets Unix. Ignoré pour les sockets dans l’espace de noms abstrait. Non pris en charge sous Windows.

Valeur par défaut : 0777

groupe_socket_unix

Nom du groupe à utiliser pour la socket Unix. Ignoré pour les sockets dans l’espace de noms abstrait. Non pris en charge sous Windows.

Par défaut : non défini

utilisateur

Si défini, spécifie l’utilisateur Unix auquel passer après le démarrage. Fonctionne uniquement si PgBouncer est lancé en tant qu’utilisateur root ou s’il est déjà en cours d’exécution en tant qu’utilisateur donné. Non pris en charge sous Windows.

Par défaut : non défini

mode_pool

Spécifie quand une connexion serveur peut être réutilisée par d’autres clients.

session : Le serveur est rendu au pool après la déconnexion du client. Valeur par défaut.
transaction : Le serveur est rendu au pool après la fin de la transaction.
statement : Le serveur est rendu au pool après la fin de la requête. Les transactions étendant sur plusieurs instructions sont interdites en ce mode.

max_client_conn

Nombre maximal de connexions clients autorisées.

Lorsque ce paramètre est augmenté, les limites de descripteurs de fichiers du système d’exploitation doivent également être ajustées. Notez que le nombre de descripteurs de fichiers utilisés potentiellement dépasse max_client_conn. Si chaque utilisateur se connecte sous son propre nom d’utilisateur au serveur, le maximum théorique utilisé est :

max_client_conn + (max pool_size * total databases * total users)

Si un utilisateur de base de données est spécifié dans la chaîne de connexion (tous les utilisateurs se connectent sous le même nom d’utilisateur), le maximum théorique est :

max_client_conn + (max pool_size * total databases)

Le nombre maximum théorique ne devrait jamais être atteint, sauf si quelqu’un conçoit délibérément une charge spécifique à cet effet. Toutefois, cela signifie que vous devez définir le nombre de descripteurs de fichiers à une valeur suffisamment élevée pour garantir une sécurité.

Recherchez ulimit dans la page de manuel de votre shell préféré. Note : ulimit n’est pas applicable dans un environnement Windows.

Valeur par défaut : 100

taille_pool_par_defaut

Le nombre maximal de connexions serveur autorisées par couple utilisateur/base de données. Peut être remplacé par pool_size dans la configuration par base de données et par utilisateur ; il s’agit de la valeur par défaut utilisée si aucun pool_size spécifique n’est défini pour une base de données ou un utilisateur donné.

Valeur par défaut : 20

taille_min_pool

Ajoutez davantage de connexions serveur à la pool si le nombre est inférieur à cette valeur. Améliore le comportement lorsque la charge normale revient soudainement après une période d’inactivité totale. La valeur est effectivement limitée au nombre maximal de connexions dans la pool.

Appliqué uniquement aux pools où au moins l’une des conditions suivantes est vraie :

l’entrée dans la section [database] pour le pool a une valeur définie pour la clé user (appelée utilisateur forcé)
il y a au moins un client connecté au pool

Par défaut : 0 (désactivé)

taille_piscine_reserve

Nombre de connexions supplémentaires autorisées vers un pool (voir reserve_pool_timeout). 0 désactive.

Par défaut : 0 (désactivé)

timeout_reserve_pool

Si un client n’a pas été servi pendant cette durée, utilisez des connexions supplémentaires provenant du pool de réserve. La valeur 0 désactive cette fonctionnalité. [secondes]

Par défaut : 5.0

max_connexions_base_données

N’autorisez pas plus de ce nombre de connexions serveur par base de données (quelle que soit l’utilisateur). Cette limite tient compte de la base de données PgBouncer à laquelle le client est connecté, et non de la base de données PostgreSQL de la connexion sortante.

Cela peut également être défini par base de données dans la section [databases].

Notez qu’en atteignant la limite, la fermeture d’une connexion client vers un pool ne permettra pas immédiatement d’établir une connexion serveur pour un autre pool, car la connexion serveur du premier pool reste ouverte. Une fois que la connexion serveur est fermée (en raison du délai d’inactivité), une nouvelle connexion serveur sera immédiatement établie pour le pool en attente.

Par défaut : 0 (illimité)

max_conn_client_base_données

N’autorisez pas plus de ce nombre de connexions clients à PgBouncer par base de données (quelle que soit l’utilisateur). Cette limite tient compte de la base de données PgBouncer à laquelle le client est connecté, et non de la base de données PostgreSQL de la connexion sortante.

Il doit être défini à une valeur supérieure ou égale à max_db_connections. La différence entre ces deux valeurs peut être interprétée comme le nombre maximal de connexions à une base de données donnée pouvant être en file d’attente en attendant que les connexions actives se terminent.

Cela peut également être défini par base de données dans la section [databases].

Par défaut : 0 (illimité)

max_user_connections

N’autorisez pas plus de ce nombre de connexions serveur par utilisateur (quelle que soit la base de données). Cette limite tient compte de l’utilisateur PgBouncer associé à un pool, qui est soit l’utilisateur spécifié pour la connexion serveur, soit, en l’absence de celui-ci, l’utilisateur avec lequel le client est connecté.

Cela peut également être défini par utilisateur dans la section [users].

Par défaut : 0 (illimité)

max_user_client_connections

N’autorisez pas plus de ce nombre de connexions clients par utilisateur (indépendamment de la base de données). Cette valeur doit être définie à un nombre supérieur à max_user_connections. La différence entre max_user_connections et max_user_client_connections peut être conceptualisée comme la taille maximale de la file d’attente pour l’utilisateur.

Cela peut également être défini par utilisateur dans la section [users].

Par défaut : 0 (illimité)

server_round_robin

Par défaut, PgBouncer réutilise les connexions serveur selon un mode LIFO (dernier entré, premier sorti), ce qui fait que peu de connexions supportent la charge la plus importante. Ce comportement offre les meilleures performances si vous disposez d’un seul serveur servant une base de données. Toutefois, si un système de répartition de charge (round-robin) est placé derrière une adresse de base de données (TCP, DNS ou liste d’hôtes), il est préférable que PgBouncer utilise également les connexions selon ce mode, afin d’obtenir une répartition uniforme de la charge.

Valeur par défaut : 0

suivi_des_paramètres_supplémentaires

Par défaut, PgBouncer suit les paramètres client_encoding, datestyle, timezone, standard_conforming_strings et application_name par client. Pour autoriser le suivi d’autres paramètres, ceux-ci peuvent être spécifiés ici, afin que PgBouncer sache qu’ils doivent être conservés dans le cache des variables client et restaurés sur le serveur chaque fois que le client devient actif.

Si vous devez spécifier plusieurs valeurs, utilisez une liste séparée par des virgules (par exemple, default_transaction_read_only, IntervalStyle)

Note : La plupart des paramètres ne peuvent pas être suivis de cette manière. Seuls les paramètres que PostgreSQL signale au client peuvent être suivis. PostgreSQL dispose d’une liste officielle des paramètres qu’il signale au client . Les extensions PostgreSQL peuvent toutefois modifier cette liste : elles peuvent ajouter des paramètres qu’elles signalent elles-mêmes, ou commencer à signaler des paramètres existants que PostgreSQL ne signale pas. Citrus 12.0+ en particulier provoque le signal de search_path.

Le protocole Postgres permet de spécifier des paramètres, soit directement comme un paramètre dans le paquet de démarrage, soit à l’intérieur du paquet de démarrage options . Les paramètres spécifiés par l’une ou l’autre de ces méthodes sont pris en charge par track_extra_parameters. Toutefois, il n’est pas possible d’inclure options lui-même dans track_extra_parameters, uniquement les paramètres contenus dans options.

Par défaut : IntervalStyle

ignore_startup_parameters

Par défaut, PgBouncer autorise uniquement les paramètres qu’il peut suivre dans les paquets de démarrage : client_encoding, datestyle, timezone et standard_conforming_strings. Tous les autres paramètres provoquent une erreur. Pour autoriser d’autres paramètres, ils peuvent être spécifiés ici, afin que PgBouncer sache qu’ils sont gérés par l’administrateur et qu’il puisse les ignorer.

Si vous devez spécifier plusieurs valeurs, utilisez une liste séparée par des virgules (par exemple, options,extra_float_digits)

Le protocole Postgres permet de spécifier des paramètres, soit directement comme un paramètre dans le paquet de démarrage, soit à l’intérieur du paquet de démarrage options . Les paramètres spécifiés par l’une ou l’autre de ces méthodes sont pris en charge par ignore_startup_parameters. Il est même possible d’inclure options lui-même dans track_extra_parameters, ce qui entraîne l’ignorance de tout paramètre inconnu contenu dans options.

Par défaut : vide

peer_id

L’identifiant pair utilisé pour identifier ce processus PgBouncer au sein d’un groupe de processus PgBouncer interconnectés. La valeur peer_id doit être unique au sein d’un groupe de processus PgBouncer interconnectés. Si elle est définie à 0, l’interconnexion des processus PgBouncer est désactivée. Pour plus d’informations, consultez la documentation de la section [peers]. La valeur maximale pouvant être utilisée pour peer_id est 16383.

Valeur par défaut : 0

désactiver_pqexec

Désactivez le protocole Simple Query (PQexec). Contrairement au protocole Extended Query, le protocole Simple Query permet d’envoyer plusieurs requêtes dans un même paquet, ce qui expose à certains types d’attaques par injection SQL. Sa désactivation peut améliorer la sécurité. Évidemment, cela signifie que seuls les clients utilisant exclusivement le protocole Extended Query resteront fonctionnels.

Valeur par défaut : 0

application_name_add_host

Ajoutez l’adresse IP du client et le port à la configuration du nom d’application définie au démarrage de la connexion. Cela permet d’identifier la source de requêtes incorrectes, etc. Cette logique s’applique uniquement au démarrage d’une connexion. Si application_name est modifié ultérieurement avec SET, PgBouncer ne le modifie pas à nouveau.

Valeur par défaut : 0

fichier de configuration

Affiche l’emplacement du fichier de configuration actuel. Modifier cette valeur fera que PgBouncer utilisera un autre fichier de configuration pour la prochaine RELOAD / SIGHUP.

Par défaut : fichier fourni en ligne de commande

nom_service

Utilisé lors de l’enregistrement du service win32.

Valeur par défaut : pgbouncer

job_name

Alias pour service_name.

stats_period

Détermine à quelle fréquence les moyennes affichées par diverses commandes SHOW sont mises à jour et à quelle fréquence les statistiques agrégées sont écrites dans le journal (mais voir log_stats). [secondes]

Valeur par défaut : 60

max_préparations_statistiques

Lorsque cette valeur est différente de zéro, PgBouncer suit les commandes liées aux instructions préparées nommées au niveau du protocole envoyées par le client en mode transaction ou pooling d’instructions. PgBouncer garantit que toute instruction préparée par un client est disponible sur la connexion serveur d’arrière-plan. Même lorsque l’instruction a été initialement préparée sur une autre connexion serveur.

PgBouncer examine internement toutes les requêtes envoyées par les clients sous forme de requête préparée, et attribue à chaque chaîne de requête unique un nom interne au format PGBOUNCER_{unique_id}. Si la même chaîne de requête est préparée plusieurs fois (éventuellement par des clients différents), ces requêtes partagent le même nom interne. PgBouncer ne prépare la requête sur le serveur PostgreSQL réel qu’en utilisant le nom interne (et non le nom fourni par le client). PgBouncer suit le nom que le client a attribué à chaque requête préparée. Il réécrit ensuite chaque commande utilisant une requête préparée en remplaçant le nom côté client par le nom interne (par exemple, en remplaçant my_prepared_statement par PGBOUNCER_123) avant de transmettre cette commande au serveur. Plus important encore, si la requête préparée que le client souhaite exécuter n’est pas encore préparée sur le serveur (par exemple, parce qu’un serveur différent est désormais affecté au client que lors de la préparation de la requête), alors PgBouncer prépare la requête de manière transparente avant de l’exécuter.

Note : Le suivi et la réécriture des commandes de requêtes préparées ne fonctionnent pas pour les commandes de requêtes préparées au niveau SQL, aussi PREPARE, EXECUTE et DEALLOCATE sont-ils acheminés directement vers Postgres. L’exception à cette règle concerne les commandes DEALLOCATE ALL et DISCARD ALL, qui fonctionnent comme prévu et effacent les requêtes préparées que PgBouncer a suivies pour le client qui envoie cette commande.

La valeur réelle de ce paramètre contrôle le nombre d’instructions préparées conservées actives dans un cache LRU sur une connexion serveur unique. Lorsque ce paramètre est défini à 0, le support des instructions préparées est désactivé pour le pooling de transactions et le pooling d’instructions. Pour obtenir les meilleurs performances, vous devez veiller à ce que cette valeur soit supérieure au nombre d’instructions préparées couramment utilisées par votre application. Prenez en compte que plus cette valeur est élevée, plus la consommation mémoire de chaque connexion PgBouncer sur votre serveur PostgreSQL sera importante, car davantage d’instructions seront conservées préparées sur ces connexions. Cela augmente également la consommation mémoire de PgBouncer lui-même, car il doit maintenant suivre les chaînes de requêtes.

L’impact sur la mémoire utilisée par PgBouncer n’est toutefois pas important :

Chaque requête unique est stockée une seule fois dans un cache de requêtes global.
Chaque connexion client conserve une mémoire tampon utilisée pour réécrire les paquets. Cette mémoire tampon ne dépasse pas 4 fois la taille de pkt_buf. Ce plafond est généralement non atteint, cela ne se produit que lorsque les requêtes contenues dans vos instructions préparées sont comprises entre 2 et 4 fois la taille de pkt_buf.

Considérez le scénario suivant comme exemple :

Il y a 1000 clients actifs
Les clients préparent 200 requêtes uniques
La taille moyenne d’une requête est de 5kB
La valeur du paramètre pkt_buf est définie par défaut à 4096 (4kB)

Ensuite, PgBouncer a besoin au plus de la quantité suivante de mémoire pour gérer ces requêtes préparées :

200 x 5kB + 1000 x 4 x 4kB = ~17MB of memory.

Le suivi des requêtes préparées entraîne non seulement un coût mémoire, mais aussi une utilisation accrue du CPU, car PgBouncer doit inspecter et réécrire les requêtes. Plusieurs instances de PgBouncer peuvent écouter sur le même port afin d’utiliser plusieurs cœurs pour le traitement ; consultez la documentation de l’option so_reuseport pour plus de détails .

Bien entendu, les requêtes préparées offrent également des bénéfices en termes de performance. Tout comme lors d’une connexion directe à PostgreSQL, en préparant une requête exécutée plusieurs fois, on réduit la quantité totale d’analyse syntaxique et de planification nécessaire. La manière dont PgBouncer suit les requêtes préparées est particulièrement avantageuse pour les performances lorsque plusieurs clients préparent la même requête. Comme les connexions clients réutilisent automatiquement une requête préparée sur une connexion serveur, même si elle a été préparée par un autre client. Par exemple, si vous avez un pool_size de 20 et que 100 clients préparent exactement la même requête, alors la requête n’est préparée (et donc analysée) que 20 fois sur le serveur PostgreSQL.

La réutilisation des requêtes préparées présente un inconvénient. Si les types de retour ou d’argument d’une requête préparée changent entre deux exécutions, PostgreSQL lève actuellement une erreur telle que :

ERROR:  cached plan must not change result type

Vous pouvez éviter ces erreurs en ne faisant pas coexister plusieurs clients utilisant exactement la même chaîne de requête dans une instruction préparée, tout en attendant des types d’arguments ou de résultats différents. L’une des causes les plus fréquentes de ce problème survient lors d’une migration DDL, par exemple lorsqu’une nouvelle colonne est ajoutée ou qu’un type de colonne est modifié sur une table existante. Dans ces cas, vous pouvez exécuter RECONNECT sur la console d’administration de PgBouncer après la migration afin de forcer la re-préparation de la requête et faire disparaître l’erreur.

Valeur par défaut : 200

nombre_d_itérations_scram

Nombre d’itérations de calcul à effectuer lors du hachage d’un mot de passe à l’aide de SCRAM-SHA-256. Un nombre plus élevé d’itérations offre une protection renforcée contre les attaques par force brute sur les mots de passe stockés, mais ralentit l’authentification.

Valeur par défaut : 4096

Paramètres d’authentification

PgBouncer gère son propre mécanisme d’authentification des clients et dispose de sa propre base d’utilisateurs. Ces paramètres contrôlent ce comportement.

type_d’authentification

Comment authentifier les utilisateurs.

cert: Le client doit se connecter via une connexion TLS munie d’un certificat client valide. Le nom d’utilisateur est ensuite extrait du champ CommonName du certificat.
md5: Utiliser la vérification de mot de passe basée sur MD5. Il s’agit de la méthode d’authentification par défaut. auth_file peut contenir à la fois des mots de passe chiffrés en MD5 et des mots de passe en clair. Si md5 est configuré et qu’un utilisateur dispose d’un secret SCRAM, l’authentification SCRAM est utilisée automatiquement à la place.
scram-sha-256: Utiliser la vérification de mot de passe avec SCRAM-SHA-256. auth_file doit contenir des secrets SCRAM ou des mots de passe en clair.
plain: Le mot de passe en clair est transmis sur le réseau. Obsolète.
trust: Aucune authentification n’est effectuée. Le nom d’utilisateur doit toutefois exister dans auth_file.
any: Comme la méthode trust, mais le nom d’utilisateur fourni est ignoré. Nécessite que toutes les bases de données soient configurées pour se connecter en tant qu’utilisateur spécifique. En outre, la base de données console autorise tout utilisateur à se connecter en tant qu’administrateur.
hba: Le type d’authentification réel est chargé à partir de auth_hba_file. Cela permet d’utiliser différentes méthodes d’authentification pour différents chemins d’accès, par exemple : les connexions via socket Unix utilisent la méthode d’authentification peer, les connexions via TCP doivent utiliser TLS.
ldap: Les utilisateurs sont authentifiés contre un serveur LDAP, comme dans PostgreSQL (voir https://www.postgresql.org/docs/current/auth-ldap.html pour les détails). Les options de connexion LDAP sont configurées à l’aide du paramètre auth_ldap_options, ou de manière alternative dans auth_hba_file.
pam: PAM est utilisé pour authentifier les utilisateurs, auth_file est ignoré. Cette méthode n’est pas compatible avec les bases de données utilisant l’option auth_user. Le nom de service transmis à PAM est « pgbouncer ». pam n’est pas pris en charge dans le fichier de configuration HBA.

auth_hba_file

Fichier de configuration HBA à utiliser lorsque auth_type est hba. Voir la section Format du fichier HBA ci-dessous pour les détails.

Par défaut : non défini

fichier_auth_ident

Fichier de mappage d’identité à utiliser lorsque auth_type est hba et qu’un mappage d’utilisateur sera défini. Voir la section Format du fichier de mappage d’identité ci-dessous pour les détails.

Par défaut : non défini

fichier_auth

Nom du fichier à charger pour les noms d’utilisateur et les mots de passe. Voir la section Format du fichier d’authentification ci-dessous pour les détails.

La plupart des types d’authentification (voir ci-dessus) exigent que soit défini auth_file soit auth_user ; sinon, aucun utilisateur ne serait défini.

Par défaut : non défini

auth_user

Si auth_user est défini, tout utilisateur non spécifié dans auth_file sera interrogé via la requête auth_query depuis pg_authid dans la base de données, en utilisant auth_user. Le mot de passe de auth_user sera extrait de auth_file. (Si auth_user n’exige pas de mot de passe, alors il n’est pas nécessaire de le définir dans auth_file.)

L’accès direct à pg_authid nécessite des droits d’administrateur. Il est préférable d’utiliser un utilisateur non superutilisateur qui appelle une fonction définie en tant que SECURITY DEFINER.

Par défaut : non défini

auth_query

Requête permettant de charger le mot de passe de l’utilisateur depuis la base de données.

Notez que la requête s’exécute dans la base de données cible. Ainsi, si une fonction est utilisée, elle doit être installée dans chaque base de données.

Valeur par défaut : SELECT rolname, CASE WHEN rolvaliduntil < now() THEN NULL ELSE rolpassword END FROM pg_authid WHERE rolname=$1 AND rolcanlogin

auth_dbname

Nom de la base de données dans la section [database] à utiliser à des fins d’authentification. Cette option peut être globale ou remplacée dans la chaîne de connexion si ce paramètre est spécifié.

auth_ldap_options

Options de connexion LDAP à utiliser si auth_type est ldap. (Non utilisées si l’authentification est configurée via auth_hba_file.) Exemple :

auth_ldap_options = ldapurl="ldap://127.0.0.1:12345/dc=example,dc=net?uid?sub"

Paramètres de journalisation

journal système

Active ou désactive le journalisation syslog. Sous Windows, le journal des événements est utilisé à la place.

Valeur par défaut : 0

syslog_ident

Sous quel nom envoyer les journaux à syslog.

Par défaut : pgbouncer (nom du programme)

facility_syslog

Sur quelle installation envoyer les journaux vers syslog. Possibilités : auth, authpriv, daemon, user, local0-7.

Valeur par défaut : daemon

log_connections

Enregistrer les connexions réussies.

Valeur par défaut : 1

log_disconnections

Journaliser les déconnexions avec leurs raisons.

Valeur par défaut : 1

log_pooler_errors

Enregistre les messages d’erreur que le pooler envoie aux clients.

Valeur par défaut : 1

log_stats

Écrire les statistiques agrégées dans le journal toutes les stats_period. Cette fonction peut être désactivée si des outils de surveillance externes sont utilisés pour récupérer les mêmes données à partir des commandes SHOW.

Valeur par défaut : 1

verbose

Augmenter le niveau de verbosité. Correspond à l’option -v en ligne de commande. Par exemple, utiliser -v -v en ligne de commande équivaut à verbose=2. 3 est le niveau de verbosité le plus élevé actuellement pris en charge.

Valeur par défaut : 0

Contrôle d’accès à la console

administrateurs

Liste séparée par des virgules des utilisateurs de base de données autorisés à se connecter et à exécuter toutes les commandes sur la console d’administration. Ignorée lorsque auth_type est égal à any, auquel cas tout nom d’utilisateur est autorisé en tant qu’administrateur.

Par défaut : vide

stats_users

Liste séparée par des virgules des utilisateurs de base de données autorisés à se connecter et à exécuter des requêtes en lecture seule sur la console. Cela signifie toutes les commandes SHOW sauf SHOW FDS.

Par défaut : vide

Vérifications de santé des connexions, délais d’attente

reset_query_serveur

Requête envoyée au serveur lors de la libération de la connexion, avant de la rendre disponible aux autres clients. À ce moment, aucune transaction n’est en cours, donc la valeur ne doit pas inclure ABORT ni ROLLBACK.

La requête doit nettoyer tout changement apporté à la session de base de données afin que le client suivant obtienne une connexion dans un état défini. La valeur par défaut est DISCARD ALL, qui supprime tout, mais cela laisse le client suivant sans état pré-caché. Elle peut être rendue plus légère, par exemple DEALLOCATE ALL, qui ne supprime que les requêtes préparées, si l’application ne se dérègle pas lorsque certaines informations sont conservées.

Lorsqu’un pooling de transactions est utilisé, le server_reset_query n’est pas utilisé, car, en ce mode, les clients ne doivent pas utiliser de fonctionnalités liées à la session, puisque chaque transaction est effectuée sur une connexion différente et donc dans un état de session différent.

Valeur par défaut : DISCARD ALL

server_reset_query_always

Si server_reset_query doit être exécuté dans tous les modes de pool. Lorsque ce paramètre est désactivé (valeur par défaut), server_reset_query ne sera exécuté que dans les pools en mode poolisation de sessions. Les connexions en mode poolisation de transactions n’ont pas besoin d’une requête de réinitialisation.

Ce paramètre sert à contourner les configurations défectueuses qui exécutent des applications utilisant des fonctionnalités de session sur un PgBouncer configuré en poolage par transaction. Il transforme une panne aléatoire en une panne déterministe : les clients perdent toujours leur état après chaque transaction.

Valeur par défaut : 0

délai_vérification_serveur

Durée pendant laquelle les connexions libérées sont conservées disponibles pour une réutilisation immédiate, sans exécuter server_check_query sur celle-ci. Si la valeur est 0, le contrôle est toujours exécuté.

Par défaut : 30.0

server_check_query

Requête simple sans action pour vérifier si la connexion au serveur est active.

Si une chaîne vide, alors la vérification de cohérence est désactivée.

Si <empty>, envoyer une requête vide en tant que vérification de cohérence.

Valeur par défaut : <empty>

server_fast_close

Déconnecte un serveur en mode pooling de sessions immédiatement ou après la fin de la transaction en cours s’il est en mode “close_needed” (défini par RECONNECT, RELOAD modifiant les paramètres de connexion ou un changement DNS), plutôt que d’attendre la fin de la session. En mode pooling de transactions ou pooling d’instructions, cela n’a aucun effet, car c’est le comportement par défaut dans ces modes.

Si, en raison de ce paramètre, une connexion serveur est fermée avant la fin de la session client, la connexion client est également fermée. Cela garantit que le client détecte que la session a été interrompue.

Ce paramètre permet que les modifications de configuration de connexion prennent effet plus rapidement lorsque le pooling de sessions et des sessions longues sont utilisés. Le désavantage est que les sessions clients risquent d’être interrompues par un changement de configuration, ce qui impose aux applications clientes de prévoir une logique de reconnexion et de rétablissement de l’état de session. Toutefois, notez qu’aucune transaction en cours ne sera perdue, car les transactions en cours ne sont pas interrompues, uniquement les sessions inactives.

Valeur par défaut : 0

durée_de_vie_serveur

Le pooler fermera une connexion serveur inutilisée (non actuellement liée à une connexion client) qui a été établie depuis plus longtemps que cette durée. Une valeur de 0 signifie que la connexion ne doit être utilisée qu’une seule fois, puis fermée. [secondes]

Cela peut également être défini par base de données dans la section [databases].

Par défaut : 3600.0

server_idle_timeout

Si une connexion vers un serveur est restée inactif plus de ce nombre de secondes, elle sera fermée. Si cette valeur est 0, ce délai d’expiration est désactivé. [secondes]

Par défaut : 600.0

server_connect_timeout

Si la connexion et la connexion à l’utilisateur ne sont pas terminées dans cet intervalle, la connexion sera fermée. [secondes]

Par défaut : 15.0

tentative_de_connexion_au_serveur_avec_reconnexion

Si la connexion au serveur échoue, en raison d’un échec de connexion ou d’une authentification, le pooler attend cette durée avant de tenter à nouveau de se connecter. Pendant l’intervalle d’attente, les nouveaux clients tentant de se connecter au serveur défaillant obtiennent immédiatement une erreur, sans autre tentative de connexion. [secondes]

Le but de ce comportement est que les clients ne s’accumulent pas inutilement en attente d’une connexion serveur lorsque ce dernier n’est pas opérationnel. Toutefois, cela signifie également qu’en cas de défaillance temporaire du serveur, par exemple lors d’un redémarrage ou en cas de configuration erronée, le pooler ne tentera de se reconnecter à celui-ci qu’au moins après cette durée. Les événements planifiés, tels que les redémarrages, doivent normalement être gérés à l’aide de la commande PAUSE afin d’éviter ce délai.

Par défaut : 15.0

client_login_timeout

Si un client se connecte mais ne parvient pas à se connecter dans ce délai, il sera déconnecté. Nécessaire principalement pour éviter les connexions mortes bloquant SUSPEND et empêchant ainsi le redémarrage en ligne. [secondes]

Par défaut : 60.0

autodb_idle_timeout

Si les pools de bases de données créés automatiquement (via *) n’ont pas été utilisés pendant ce nombre de secondes, ils sont libérés. L’inconvénient de cette approche est qu’ils perdent également leurs statistiques. [secondes]

Par défaut : 3600.0

dns_max_ttl

Durée de mise en mémoire tampon des requêtes DNS. Le TTL réel DNS est ignoré. [secondes]

Par défaut : 15.0

dns_nxdomain_ttl

Durée de mise en cache des erreurs DNS et des requêtes DNS NXDOMAIN. [secondes]

Par défaut : 15.0

période_vérification_zone_dns

Période d’inspection pour détecter un changement du numéro de série d’une zone.

PgBouncer peut collecter des zones DNS à partir des noms d’hôte (tout ce qui suit le premier point) et vérifier périodiquement si le numéro de série de la zone a changé. Si une modification est détectée, tous les noms d’hôte de cette zone sont à nouveau résolus. Si l’adresse IP d’un hôte change, ses connexions sont invalidées.

Fonctionne uniquement avec le backend c-ares (configure option --with-cares).

Par défaut : 0.0 (désactivé)

fichier_resolv_conf

Emplacement d’un fichier resolv.conf personnalisé. Cela permet de spécifier des serveurs DNS personnalisés et éventuellement d’autres options de résolution de noms, indépendamment de la configuration globale du système d’exploitation.

Exige un backend evdns (>= 2.0.3) ou c-ares (>= 1.15.0).

L’analyse du fichier est effectuée par la bibliothèque backend DNS, et non par PgBouncer ; reportez-vous à la documentation de la bibliothèque pour obtenir les détails sur la syntaxe et les directives autorisées.

Par défaut : vide (utiliser les paramètres par défaut du système d’exploitation)

query_wait_notify

Délai pendant lequel un client sera mis en file d’attente avant que PgBouncer n’envoie un message de notification indiquant qu’il est en file d’attente. [secondes]

Une valeur de 0 désactive ce message de notification.

Valeur par défaut : 5

Paramètres TLS

Si le contenu de l’un des fichiers cert ou key est modifié sans changer le nom de fichier réel dans la configuration, les nouveaux contenus seront utilisés pour les nouvelles connexions après une relecture. Les connexions existantes ne seront toutefois pas fermées. Si, pour des raisons de sécurité, il est nécessaire que toutes les connexions utilisent les nouveaux fichiers dès que possible, il est conseillé d’exécuter RECONNECT après la relecture.

Modifier l’un quelconque paramètre TLS déclenche automatiquement une RECONNECT pour des raisons de sécurité.

client_tls_sslmode

Mode TLS à utiliser pour les connexions provenant des clients. Les connexions TLS sont désactivées par défaut. Lorsqu’elles sont activées, client_tls_key_file et client_tls_cert_file doivent également être configurés afin de définir la clé et le certificat utilisés par PgBouncer pour accepter les connexions clients. Le format de fichier de certificat le plus courant utilisable par PgBouncer est PEM.

disable: TCP brut. Si le client demande TLS, cela est ignoré. Valeur par défaut.
allow: Si le client demande TLS, il est utilisé. Sinon, TCP brut est utilisé. Si le client présente un certificat client, il n’est pas validé.
prefer: Identique à allow.
require: Le client doit utiliser TLS. Sinon, la connexion est rejetée. Si le client présente un certificat client, il n’est pas validé.
verify-ca: Le client doit utiliser TLS avec un certificat client valide.
verify-full: Identique à verify-ca.

client_tls_key_file

Clé privée de PgBouncer pour accepter les connexions clients.

Par défaut : non défini

client_tls_cert_file

Certificat associé à la clé privée. Les clients peuvent le valider.

Par défaut : non défini

client_tls_ca_file

Fichier de certificat racine utilisé pour valider les certificats clients.

Par défaut : non défini

client_tls_protocols

Quelles versions du protocole TLS sont autorisées. Valeurs autorisées : tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.3. Raccourcis : all (tlsv1.0,tlsv1.1,tlsv1.2,tlsv1.3), secure (tlsv1.2,tlsv1.3).

Par défaut : secure

client_tls_ciphers

Cipheres TLS autorisés, au format OpenSSL. Raccourcis :

default/secure/fast/normal (tous utilisent les paramètres par défaut OpenSSL du système)
all (active tous les chiffrements, non recommandé)

Seules les connexions utilisant la version TLS 1.2 et inférieure sont concernées. Pour la version 1.3, voir client_tls13_ciphers ci-dessous.

Valeur par défaut : default

client_tls13_ciphers

Cipheres TLS v1.3 autorisés. Si vide, il utilisera la valeur de client_tls_ciphers. Valeurs autorisées :

TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
TLS_AES_128_CCM_8_SHA256
TLS_AES_128_CCM_SHA256

Seules les connexions utilisant TLS version 1.3 et supérieure sont concernées. Pour les versions 1.2 et inférieures, voir client_tls_ciphers.

Valeur par défaut : <empty>

client_tls_ecdhcurve

Nom de la courbe elliptique à utiliser pour les échanges de clés ECDH.

Valeurs autorisées : none (DH désactivé), auto (ECDH 256 bits), nom de courbe

Valeur par défaut : auto

client_tls_dheparams

Type d’échange de clés DHE.

Valeurs autorisées : none (DH désactivé), auto (DH 2048 bits), legacy (DH 1024 bits)

Valeur par défaut : auto

server_tls_sslmode

Mode TLS à utiliser pour les connexions aux serveurs PostgreSQL. Le mode par défaut est prefer.

disable : TCP brut. Le serveur n’est même pas interrogé pour une connexion TLS.
allow : À corriger : si le serveur rejette le mode brut, tenter TLS ?
prefer : Une connexion TLS est toujours demandée en premier au serveur PostgreSQL. Si elle est refusée, la connexion est établie en TCP brut. Le certificat du serveur n’est pas validé. Valeur par défaut.
require : La connexion doit obligatoirement s’établir en TLS. Si le serveur la refuse, la connexion en TCP brut n’est pas tentée. Le certificat du serveur n’est pas validé.
verify-ca : La connexion doit obligatoirement s’établir en TLS et le certificat du serveur doit être valide selon server_tls_ca_file. Le nom d’hôte du serveur n’est pas vérifié par rapport au certificat.
verify-full : La connexion doit obligatoirement s’établir en TLS et le certificat du serveur doit être valide selon server_tls_ca_file. Le nom d’hôte du serveur doit correspondre aux informations du certificat.

server_tls_ca_file

Fichier de certificat racine utilisé pour valider les certificats des serveurs PostgreSQL.

Par défaut : non défini

fichier_cle_tls_serveur

Clé privée de PgBouncer pour s’authentifier auprès du serveur PostgreSQL.

Par défaut : non défini

server_tls_cert_file

Certificat associé à la clé privée. Le serveur PostgreSQL peut le valider.

Par défaut : non défini

server_tls_protocols

Quelles versions du protocole TLS sont autorisées. Valeurs autorisées : tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.3. Raccourcis : all (tlsv1.0,tlsv1.1,tlsv1.2,tlsv1.3), secure (tlsv1.2,tlsv1.3), legacy (all).

Par défaut : secure

server_tls_ciphers

Cipheres TLS autorisés, au format OpenSSL. Raccourcis :

default/secure/fast/normal (tous utilisent les paramètres par défaut OpenSSL du système)
all (active tous les chiffrements, non recommandé)

Seules les connexions utilisant la version TLS 1.2 et inférieures sont concernées. Pour la version 1.3, voir server_tls13_ciphers ci-dessous.

Valeur par défaut : default

server_tls13_ciphers

Cipheres TLS v1.3 autorisés. Si vide, il utilisera la valeur de server_tls_ciphers. Valeurs autorisées :

TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
TLS_AES_128_CCM_8_SHA256
TLS_AES_128_CCM_SHA256

Seules les connexions utilisant TLS version 1.3 et supérieure sont concernées. Pour les versions 1.2 et inférieures, voir client_tls_ciphers.

Valeur par défaut : <empty>

Délais d’attente dangereux

Définir les délais suivants peut entraîner des erreurs imprévues.

query_timeout

Requêtes exécutées plus longtemps que ce délai sont annulées. Cette option doit être utilisée uniquement avec une valeur légèrement plus petite pour le paramètre côté serveur statement_timeout, afin de ne s’appliquer qu’en cas de problèmes réseau. [secondes]

Par défaut : 0.0 (désactivé)

query_wait_timeout

Temps maximal autorisé aux requêtes pour attendre leur exécution. Si la requête n’est pas affectée à un serveur pendant cette durée, le client est déconnecté. La valeur 0 désactive cette fonctionnalité. Si cette option est désactivée, les clients seront mis en file d’attente indéfiniment. [secondes]

Ce paramètre est utilisé pour empêcher les serveurs inactifs de consommer des connexions. Il est également utile lorsque le serveur est hors ligne ou refuse les connexions pour quelque raison que ce soit.

Par défaut : 120.0

timeout_attente_annulation

Temps maximal autorisé pour les demandes de annulation en attente d’exécution. Si la demande d’annulation n’est pas affectée à un serveur pendant cette durée, le client est déconnecté. 0 désactive cette fonctionnalité. Si cette option est désactivée, les demandes d’annulation seront mises en file d’attente indéfiniment. [secondes]

Ce paramètre est utilisé pour empêcher qu’un client se bloque lorsque l’annulation ne peut être acheminée en raison de la panne du serveur.

Par défaut : 10.0

délai d’inactivité du client

Les connexions clients inactives depuis plus de ce nombre de secondes sont fermées. Cette valeur doit être supérieure aux paramètres de durée de vie des connexions côté client, et n’est utilisée qu’en cas de problèmes réseau. [secondes]

Par défaut : 0.0 (désactivé)

idle_transaction_timeout

Si un client reste plus longtemps dans l’état « idle in transaction », il sera déconnecté. [secondes]

Par défaut : 0.0 (désactivé)

transaction_timeout

Si un client reste plus longtemps dans l’état « en transaction », il sera déconnecté. [secondes]

Par défaut : 0.0 (désactivé)

délai_d’attente_suspendu

Durée d’attente pour l’écriture du tampon pendant un SUSPEND ou un redémarrage (-R). Une connexion est fermée si l’écriture échoue. [secondes]

Valeur par défaut : 10

Paramètres réseau de bas niveau

tampon_paquet

Taille du tampon interne pour les paquets. Influence la taille des paquets TCP envoyés et l’utilisation mémoire globale. Les paquets réels libpq peuvent être plus grands que cette valeur, il n’est donc pas nécessaire de la définir élevée.

Valeur par défaut : 4096

taille_max_paquet

Taille maximale des paquets PostgreSQL autorisés par PgBouncer. Un paquet correspond soit à une requête, soit à une ligne d’un jeu de résultats. Le jeu de résultats complet peut être plus grand.

Valeur par défaut : 2147483647

listen_backlog

Argument Backlog pour listen(2). Détermine le nombre de nouvelles tentatives de connexion non traitées conservées dans la file d’attente. Lorsque la file est pleine, les nouvelles connexions supplémentaires sont rejetées.

Valeur par défaut : 128

sbuf_loopcnt

Nombre de fois où les données doivent être traitées sur une connexion avant de passer à l’étape suivante. Sans cette limite, une connexion avec un grand jeu de résultats peut bloquer PgBouncer pendant une longue période. Une boucle traite une quantité de données égale à pkt_buf. La valeur 0 signifie qu’aucune limite n’est appliquée.

Valeur par défaut : 5

so_reuseport

Spécifie si l’option de socket SO_REUSEPORT doit être définie sur les sockets TCP d’écoute. Sur certains systèmes d’exploitation, cela permet d’exécuter plusieurs instances de PgBouncer sur le même hôte, écoutant sur le même port, avec une répartition automatique des connexions par le noyau. Cette option permet à PgBouncer d’utiliser davantage de cœurs processeurs. (PgBouncer est monothread et utilise un cœur processeur par instance.)

Le comportement en détail dépend du noyau du système d’exploitation. À la date de rédaction de ce document, ce paramètre produit l’effet souhaité sur Linux (versions suffisamment récentes), DragonFlyBSD et FreeBSD. (Sur FreeBSD, il applique l’option de socket SO_REUSEPORT_LB à la place.) Certains autres systèmes d’exploitation prennent en charge l’option de socket, mais celle-ci n’aura pas l’effet souhaité : elle permettra à plusieurs processus de se lier au même port, mais seul l’un d’entre eux recevra les connexions. Consultez la documentation de votre système d’exploitation concernant setsockopt() pour plus de détails.

Sur les systèmes qui ne prennent pas du tout en charge l’option de socket, activer ce paramètre entraînera une erreur.

Chaque instance de PgBouncer sur le même hôte doit disposer de paramètres différents au moins pour unix_socket_dir et pidfile, ainsi que pour logfile si celui-ci est utilisé. Notez également que, si vous utilisez cette option, il devient impossible de se connecter à une instance spécifique de PgBouncer via TCP/IP, ce qui peut avoir des implications pour la surveillance et la collecte de métriques.

Pour garantir que les annulations de requêtes fonctionnent correctement, vous devez configurer une réplication entre les différents processus PgBouncer. Pour plus de détails, reportez-vous à la documentation relative à l’option de configuration peer_id et à la section de configuration peers. Un exemple utilisant la réplication et so_reuseport est également disponible dans la section d’exemples de ces documents.

Valeur par défaut : 0

tcp_defer_accept

Définit l’option de socket TCP_DEFER_ACCEPT ; consultez man 7 tcp pour les détails. (Il s’agit d’une option booléenne : 1 signifie activée. La valeur réelle définie lorsqu’elle est activée est actuellement codée en dur à 45 secondes.)

Cela n’est actuellement pris en charge que sous Linux.

Valeur par défaut : 1 sous Linux, sinon 0

tcp_socket_buffer

Par défaut : non défini

tcp_keepalive

Active la fonctionnalité de keepalive basique avec les paramètres par défaut du système d’exploitation.

Sur Linux, les valeurs par défaut du système sont tcp_keepidle=7200, tcp_keepintvl=75, tcp_keepcnt=9. Elles sont probablement similaires sur d’autres systèmes d’exploitation.

Valeur par défaut : 1

tcp_keepcnt

Par défaut : non défini

tcp_keepidle

Par défaut : non défini

tcp_keepintvl

Par défaut : non défini

tcp_user_timeout

Définit l’option de socket TCP_USER_TIMEOUT. Cela précise la durée maximale, en millisecondes, pendant laquelle les données transmises peuvent rester non reconnues avant que la connexion TCP ne soit fermée de force. Si cette valeur est définie à 0, la valeur par défaut du système d’exploitation est utilisée.

Cela n’est actuellement pris en charge que sous Linux.

Valeur par défaut : 0

Section [databases]

La section [databases] définit les noms des bases de données auxquelles les clients de PgBouncer peuvent se connecter et précise où ces connexions seront acheminées. La section contient des lignes key=value telles que

dbname = connection string

où la clé sera prise comme nom de base de données et la valeur comme chaîne de connexion, composée de paires clé=valeur de paramètres de connexion, décrites ci-dessous (similaire à libpq, mais la bibliothèque libpq réelle n’est pas utilisée et l’ensemble des fonctionnalités disponibles est différent). Exemple :

foodb = host=host1.example.com port=5432
bardb = host=localhost dbname=bazdb

Le nom de base de données peut contenir des caractères _0-9A-Za-z sans guillemets. Les noms contenant d’autres caractères doivent être cités entre guillemets standard selon la syntaxe SQL : guillemets doubles, avec "" pour une occurrence unique de guillemet double.

Le nom de base de données pgbouncer est réservé à la console d’administration et ne peut pas être utilisé comme clé ici.

* agit comme base de données de secours : si le nom exact n’existe pas, sa valeur est utilisée comme chaîne de connexion pour la base de données demandée. Par exemple, si une entrée existe (et aucune autre entrée ne l’override)

* = host=foo

puis une connexion à PgBouncer spécifiant une base de données bar se comportera effectivement comme si une entrée existait

bar = host=foo dbname=bar

existe (en profitant de la valeur par défaut de dbname étant le nom de la base côté client ; voir ci-dessous).

Les entrées de base de données créées automatiquement sont supprimées si elles restent inactives plus longtemps que le délai spécifié par le paramètre autodb_idle_timeout.

dbname

Nom de la base de données de destination.

Valeur par défaut : identique au nom de la base du côté client

hôte

Nom d’hôte ou adresse IP vers laquelle se connecter. Les noms d’hôte sont résolus au moment de la connexion, le résultat est mis en mémoire tampon par paramètre dns_max_ttl. Lorsqu’une résolution de nom d’hôte change, les connexions serveur existantes sont automatiquement fermées lorsqu’elles sont libérées (selon le mode de regroupement), et les nouvelles connexions serveur utilisent immédiatement la nouvelle résolution. Si DNS retourne plusieurs résultats, ils sont utilisés de manière cyclique.

Si la valeur commence par /, un socket Unix dans l’espace de noms du système de fichiers est utilisé. Si la valeur commence par @, un socket Unix dans l’espace de noms abstrait est utilisé.

Une liste séparée par des virgules d’hôtes ou d’adresses peut être spécifiée. Dans ce cas, les connexions sont établies de manière cyclique. (Si une liste d’hôtes contient des noms d’hôtes qui se résolvent eux-mêmes via DNS en plusieurs adresses, les systèmes de rotation opèrent de manière indépendante. Il s’agit d’une dépendance d’implémentation susceptible de changer.) Notez qu’une liste exige que tous les hôtes soient disponibles en permanence : aucun mécanisme n’existe pour ignorer les hôtes inaccessibles ou sélectionner uniquement les hôtes disponibles dans la liste ou similaire. (Cela diffère de ce qu’une liste d’hôtes dans libpq signifie.) Notez également que cela n’a d’effet que sur le choix des destinations des nouvelles connexions. Voir également le paramètre server_round_robin pour savoir comment les clients sont affectés aux connexions serveur déjà établies.

Exemples :

host=localhost
host=127.0.0.1
host=2001:0db8:85a3:0000:0000:8a2e:0370:7334
host=/var/run/postgresql
host=192.168.0.1,192.168.0.2,192.168.0.3

Par défaut : non défini, ce qui signifie utiliser une socket Unix

port

Valeur par défaut : 5432

utilisateur

Si user= est défini, toutes les connexions à la base de données cible seront établies avec l’utilisateur spécifié, ce qui signifie qu’il n’y aura qu’un seul pool pour cette base de données.

Sinon, PgBouncer se connecte à la base de données de destination avec le nom d’utilisateur du client, ce qui signifie qu’il y aura un pool par utilisateur.

mot de passe

Si aucun mot de passe n’est spécifié ici, le mot de passe provenant de auth_file sera utilisé pour l’utilisateur indiqué ci-dessus. Les formes dynamiques de découverte de mot de passe telles que auth_query ne sont pas actuellement prises en charge.

auth_user

Remplacement du paramètre global auth_user, le cas échéant.

auth_query

Remplacement du paramètre global auth_query, le cas échéant. L’intégralité de l’instruction SQL doit être entourée de guillemets simples.

auth_dbname

Remplacement du paramètre global auth_dbname, le cas échéant.

taille_pool

Définir la taille maximale des pools pour cette base de données. Si ce paramètre n’est pas défini, la valeur de default_pool_size est utilisée.

taille_min_pool

Définir la taille minimale du pool pour cette base de données. Si ce paramètre n’est pas défini, la valeur globale min_pool_size est utilisée.

Imposé uniquement si au moins l’une des conditions suivantes est vraie :

cette entrée dans la section [database] a une valeur définie pour la clé user (alias utilisateur forcé)
il y a au moins un client connecté à la pool

taille_piscine_reserve

Définir un nombre supplémentaire de connexions pour cette base de données. Si ce paramètre n’est pas défini, la valeur globale reserve_pool_size est utilisée. Pour des raisons de compatibilité descendante, reserve_pool est un alias de cette option.

query_de_connexion

Requête à exécuter après établissement d’une connexion, mais avant de permettre à tout client de l’utiliser. Si la requête génère des erreurs, celles-ci sont journalisées, mais ignorées dans les autres cas.

mode_pool

Définissez le mode de pool spécifique à cette base de données. Si ce paramètre n’est pas défini, le mode par défaut pool_mode est utilisé.

load_balance_hosts

Lorsqu’une liste séparée par des virgules est spécifiée dans host, load_balance_hosts détermine quel élément est sélectionné pour une nouvelle connexion.

Note : Ce paramètre contrôle actuellement uniquement le comportement de répartition de charge lorsqu’un string de connexion contient plusieurs hôtes, mais pas lorsqu’un enregistrement DNS d’un hôte unique fait référence à plusieurs adresses IP. Il s’agit d’une fonctionnalité manquante, donc dans une version future, ce paramètre pourrait commencer à contrôler les deux méthodes de répartition de charge.

round-robin : Une nouvelle tentative de connexion choisit l’entrée hôte suivante dans la liste.
disable : Une nouvelle connexion continue d’utiliser la même entrée hôte jusqu’à ce qu’une connexion échoue, après quoi l’entrée hôte suivante est choisie.

Il est recommandé de définir server_login_retry à une valeur inférieure à celle par défaut afin d’assurer des tentatives rapides lorsqu’un ou plusieurs hôtes sont disponibles.

Valeur par défaut : round-robin

max_connexions_base_données

Définir un maximum de connexions serveur au niveau de la base de données (c’est-à-dire que toutes les pools au sein de la base de données ne comporteront pas plus de ce nombre de connexions serveur).

max_conn_client_base_données

Configure le nombre maximum de connexions clients au niveau de la base de données. Doit être utilisé en conjonction avec max_client_conn afin de limiter le nombre de connexions que PgBouncer est autorisé à accepter.

durée_de_vie_serveur

Configurez server_lifetime par base de données. Si ce paramètre n’est pas défini, la base de données utilisera la valeur configurée au niveau de l’instance pour server_lifetime.

client_encoding

Demandez un client_encoding spécifique au serveur.

datestyle

Demandez le datestyle spécifique au serveur.

fuseau horaire

Demandez le timezone spécifique au serveur.

Section [users]

Cette section contient des lignes key=value telles que

user1 = settings

où la clé sera prise comme nom d’utilisateur et la valeur comme liste de paires clé=valeur de paramètres de configuration spécifiques à cet utilisateur. Exemple :

user1 = pool_mode=session

Seuls quelques paramètres sont disponibles ici.

Notez que lorsque auth_file est configuré, si un utilisateur est défini dans cette section mais non listé dans auth_file, PgBouncer tentera d’utiliser auth_query pour trouver le mot de passe de cet utilisateur si auth_user est défini. Si auth_user n’est pas défini, PgBouncer supposera que l’utilisateur existe et ne renverra pas de message « utilisateur introuvable » au client, mais il n’acceptera non plus aucun mot de passe fourni.

taille_pool

Définir la taille maximale des pools pour toutes les connexions de cet utilisateur. Si non défini, la base de données ou default_pool_size est utilisée.

taille_piscine_reserve

Définir le nombre de connexions supplémentaires autorisées à une pool pour cet utilisateur. Si ce paramètre n’est pas défini, la configuration de la base de données ou le reserve_pool_size global est utilisée.

mode_pool

Définir le mode de pool à utiliser pour toutes les connexions de cet utilisateur. Si non défini, le mode défini dans la base de données ou la valeur par défaut pool_mode est utilisé.

max_user_connections

Définir un maximum pour le nombre de connexions serveur par utilisateur (c’est-à-dire que tous les pools associés à l’utilisateur ne comporteront pas plus de ce nombre de connexions serveur).

query_timeout

Définissez le nombre maximal de secondes pendant lesquelles une requête utilisateur peut s’exécuter. Si ce délai est défini, il remplace le paramètre query_timeout au niveau du serveur décrit ci-dessus.

idle_transaction_timeout

Définissez le nombre maximum de secondes pendant lesquelles une transaction inactif peut rester ouverte pour un utilisateur. Si ce délai est défini, il remplace le paramètre idle_transaction_timeout au niveau du serveur décrit ci-dessus.

transaction_timeout

Définissez le nombre maximum de secondes pendant lesquelles une transaction peut rester ouverte pour un utilisateur. Si ce paramètre est défini, il remplace le délai d’attente au niveau du serveur transaction_timeout décrit ci-dessus.

délai d’inactivité du client

Définissez le délai maximal en secondes pendant lequel un client est autorisé à rester connecté sans activité à l’instance PgBouncer. Si ce délai est défini, il remplace le paramètre client_idle_timeout au niveau du serveur décrit ci-dessus.

Veuillez noter qu’il s’agit d’un délai d’attente potentiellement dangereux.

max_user_client_connections

Définir un maximum pour le nombre de connexions clients par utilisateur. Il s’agit de l’équivalent utilisateur de la configuration max_client_conn.

Section [peers]

La section [peers] définit les pairs auxquels PgBouncer peut acheminer les requêtes d’annulation et l’emplacement vers lequel ces requêtes d’annulation seront acheminées.

Les processus PgBouncer peuvent être associés en groupe en définissant une valeur peer_id et une section [peers] dans les configurations de tous les processus PgBouncer. Ces processus PgBouncer peuvent alors transférer les requêtes d’annulation vers le processus d’origine. Cela est nécessaire pour assurer le bon fonctionnement des annulations lorsque plusieurs processus PgBouncer (éventuellement sur des serveurs différents) sont situés derrière le même équilibreur de charge TCP. Les requêtes d’annulation sont envoyées via des connexions TCP différentes de celles de la requête qu’elles annulent, si bien qu’un équilibreur de charge TCP pourrait acheminer la connexion de requête d’annulation vers un processus différent de celui visé. En les associant, ces requêtes d’annulation parviennent finalement au bon processus. Une explication plus détaillée est fournie dans cette enregistrement d’une conférence .

La section contient des lignes key=value telles que

peer_id = connection string

Où la clé sera utilisée comme peer_id et la valeur comme chaîne de connexion, composée de paires clé=valeur de paramètres de connexion, décrites ci-dessous (similaire à libpq, mais la bibliothèque libpq n’est pas utilisée et l’ensemble des fonctionnalités disponibles est différent). Exemple :

1 = host=host1.example.com
2 = host=/tmp/pgbouncer-2  port=5555

Note 1 : Pour que le peering fonctionne, l’peer_id de chaque processus PgBouncer du groupe doit être unique au sein du groupe peered. La section [peers] doit contenir une entrée pour chaque identifiant de pair. Un exemple est disponible dans la section exemples de ces documents. Il est autorisé, mais non obligatoire, que la section [peers] contienne l’peer_id du PgBouncer pour lequel la configuration est définie. Une telle entrée sera ignorée, mais cette pratique est autorisée afin de faciliter la gestion des configurations. Elle permet d’utiliser la même section [peers] pour plusieurs configurations.

Note 2 : Le rattachement entre versions différentes est pris en charge à condition que tous les pairs soient du même côté de la limite de version v1.21.0. La version v1.21.0 a introduit des modifications importantes dans la manière dont les jetons d’annulation sont encodés, les rendant incompatibles avec ceux générés par les versions antérieures.

hôte

Nom d’hôte ou adresse IP vers laquelle se connecter. Les noms d’hôte sont résolus au moment de la connexion, le résultat est mis en mémoire tampon par paramètre dns_max_ttl. Si DNS retourne plusieurs résultats, ils sont utilisés de manière cyclique. Toutefois, il n’est généralement pas recommandé d’utiliser un nom d’hôte qui résout vers plusieurs adresses IP, car la requête d’annulation pourrait encore être acheminée vers le mauvais nœud, ce qui nécessiterait un nouvel acheminement (autorisé au maximum trois fois).

Exemples :

host=localhost
host=127.0.0.1
host=2001:0db8:85a3:0000:0000:8a2e:0370:7334
host=/var/run/pgbouncer-1

port

Par défaut : 6432

taille_pool

Définissez le nombre maximal de demandes d’annulation pouvant être en cours vers le pair en même temps. Il est tout à fait normal que des demandes d’annulation arrivent par vagues, par exemple lorsque le serveur Postgres sous-jacent est lent ou hors service. Il est donc important que pool_size ne soit pas trop bas afin de pouvoir gérer ces vagues.

Si ce n’est pas défini, default_pool_size est utilisé.

Directive include

Le fichier de configuration de PgBouncer peut contenir des directives include, qui spécifient un autre fichier de configuration à lire et à traiter. Cela permet de diviser le fichier de configuration en parties physiquement séparées. Les directives include ont la forme suivante :

%include filename

Si le nom de fichier n’est pas un chemin absolu, il est considéré comme relatif au répertoire de travail courant.

Format de fichier d’authentification

Cette section décrit le format du fichier spécifié par le paramètre auth_file. Il s’agit d’un fichier texte au format suivant :

"username1" "password" ...
"username2" "md5abcdef012342345" ...
"username2" "SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>"

Il doit y avoir au moins 2 champs, entourés de guillemets doubles. Le premier champ est le nom d’utilisateur et le second est soit un mot de passe en clair, soit un mot de passe haché en MD5, soit un secret SCRAM. PgBouncer ignore le reste de la ligne. Les guillemets doubles dans une valeur de champ peuvent être échappés en écrivant deux guillemets doubles.

Format de mot de passe MD5 PostgreSQL :

"md5" + md5(password + username)

L’utilisateur admin avec le mot de passe 1234 disposera d’un mot de passe haché MD5 égal à md545f2603610af569b6155c45067268c6b.

Format secret SCRAM PostgreSQL :

SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>

Consultez la documentation PostgreSQL et le RFC 5803 pour plus de détails à ce sujet.

Les mots de passe ou secrets stockés dans le fichier d’authentification servent à deux fins. Premièrement, ils sont utilisés pour vérifier les mots de passe des connexions clients entrantes, si une méthode d’authentification basée sur le mot de passe est configurée. Deuxièmement, ils sont utilisés comme mots de passe pour les connexions sortantes vers le serveur backend, si le serveur backend exige une authentification basée sur le mot de passe (à moins que le mot de passe ne soit spécifié directement dans la chaîne de connexion de la base de données).

Limitations

Si le mot de passe est stocké en clair, il peut être utilisé pour toute authentification basée sur le mot de passe utilisée par le serveur backend ; clair, MD5 ou SCRAM (voir https://www.postgresql.org/docs/current/auth-password.html pour les détails).

Les mots de passe hachés MD5 peuvent être utilisés si le serveur backend utilise l’authentification MD5 (ou si certains utilisateurs ont des mots de passe hachés MD5).

Les secrets SCRAM ne peuvent être utilisés pour se connecter à un serveur que si l’authentification du client utilise également SCRAM, si la définition de la base de données dans PgBouncer ne précise pas de nom d’utilisateur, et si les secrets SCRAM sont identiques dans PgBouncer et le serveur PostgreSQL (même sel et nombre d’itérations, et non seulement le même mot de passe). Ceci est dû à une propriété de sécurité intrinsèque du SCRAM : le secret SCRAM stocké ne peut, en lui-même, être utilisé pour dériver les identifiants de connexion.

Le fichier d’authentification peut être rédigé à la main, mais il est également utile de le générer à partir d’une autre liste d’utilisateurs et de mots de passe. Consultez ./etc/mkauth.py pour un exemple de script permettant de générer le fichier d’authentification à partir de la table système pg_authid. En alternative, utilisez auth_query à la place de auth_file afin d’éviter d’avoir à maintenir un fichier d’authentification séparé.

Remarque sur les serveurs gérés

Si le serveur backend est configuré pour utiliser l’authentification par mot de passe SCRAM, PgBouncer ne peut pas s’authentifier correctement s’il ne connaît ni a) le mot de passe utilisateur en clair, ni b) le secret SCRAM correspondant.

Certains fournisseurs de cloud (par exemple, AWS RDS) interdisent l’accès aux tables système sensibles de PostgreSQL pour récupérer les mots de passe. Même pour l’utilisateur le plus privilégié (par exemple, membre de rds_superuser), select * from pg_authid retourne ERROR: permission denied for table pg_authid. Ce comportement est connu (blog ).

Par conséquent, il est impossible de récupérer un secret SCRAM existant une fois qu’il a été stocké sur un serveur géré, ce qui rend difficile la configuration de PgBouncer pour utiliser le même secret SCRAM. Toutefois, il est encore possible de configurer et d’utiliser le secret SCRAM des deux côtés en utilisant la méthode suivante :

Générez le secret SCRAM pour un mot de passe arbitraire à l’aide d’un outil capable d’afficher le secret. Par exemple, psql --echo-hidden et la commande \password affichent le secret SCRAM sur la console avant de l’envoyer au serveur.

$ psql --echo-hidden <connection_string>
postgres=# \password <role_name>
Enter new password for user "<role_name>":
Enter it again:
********* QUERY **********
ALTER USER <role_name> PASSWORD 'SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>'
**************************

Notez le secret SCRAM issu de la requête et définissez-le dans userlist.txt de PgBouncer.

Si vous avez utilisé un outil autre que psql --echo-hidden, vous devez également définir le secret SCRAM sur le serveur (vous pouvez utiliser ALTER ROLE <role_name> PASSWORD '<scram_secret>' à cette fin).

Format du fichier HBA

L’emplacement du fichier HBA est spécifié par le paramètre auth_hba_file. Il n’est utilisé que si auth_type est défini à hba.

Le fichier suit le format du fichier PostgreSQL pg_hba.conf (voir https://www.postgresql.org/docs/current/auth-pg-hba-conf.html ).

Types de registre pris en charge : local, host, hostssl, hostnossl.
Champ base de données : prend en charge all, replication, sameuser, @file, plusieurs noms. Non pris en charge : samerole, samegroup.
Champ nom d’utilisateur : prend en charge all, @file, plusieurs noms. Non pris en charge : +groupname.
Champ adresse : prend en charge all, IPv4, IPv6. Non pris en charge : samehost, samenet, noms DNS, préfixes de domaine.
Champ méthode d’authentification : seules les méthodes prises en charge par le auth_type de PgBouncer sont prises en charge, ainsi que peer et reject, à l’exception de any et pam, qui ne fonctionnent qu’à l’échelle globale.
Le paramètre de mappage de nom d’utilisateur (map=) est pris en charge lorsque auth_type est défini à cert ou peer.

Format du fichier de mappage d’identité

L’emplacement du fichier de correspondance ident est spécifié par le paramètre auth_ident_file. Il n’est chargé que si auth_type est défini sur hba.

Le format de fichier est une variante simplifiée du fichier de correspondance ident PostgreSQL (voir https://www.postgresql.org/docs/current/auth-username-maps.html ).

Les lignes prises en charge sont uniquement au format map-name system-username database-username.
Aucun support n’est assuré pour l’inclusion de fichiers ou de répertoires.
Champ nom d’utilisateur système : non pris en charge : expressions régulières.
Champ nom d’utilisateur base de données : prend en charge all ou un seul nom d’utilisateur Postgres. Non pris en charge : +groupname, expressions régulières.

Exemples

Exemple de configuration minimaliste :

[databases]
template1 = host=localhost dbname=template1 auth_user=someuser

[pgbouncer]
pool_mode = session
listen_port = 6432
listen_addr = localhost
auth_type = md5
auth_file = users.txt
logfile = pgbouncer.log
pidfile = pgbouncer.pid
admin_users = someuser
stats_users = stat_collector

Exemples de bases de données :

[databases]

; foodb over Unix socket
foodb =

; redirect bardb to bazdb on localhost
bardb = host=localhost dbname=bazdb

; access to destination database will go with single user
forcedb = host=localhost port=300 user=baz password=foo client_encoding=UNICODE datestyle=ISO

Exemple d’une fonction sécurisée pour auth_query :

CREATE OR REPLACE FUNCTION pgbouncer.user_lookup(in i_username text, out uname text, out phash text)
RETURNS record AS $$
BEGIN
    SELECT rolname, CASE WHEN rolvaliduntil < now() THEN NULL ELSE rolpassword END
    FROM pg_authid
    WHERE rolname=i_username AND rolcanlogin
    INTO uname, phash;
    RETURN;
END;
$$ LANGUAGE plpgsql
   SECURITY DEFINER
   -- Set a secure search_path: trusted schema(s), then 'pg_temp'.
   SET search_path = pg_catalog, pg_temp;
REVOKE ALL ON FUNCTION pgbouncer.user_lookup(text) FROM public, pgbouncer;
GRANT EXECUTE ON FUNCTION pgbouncer.user_lookup(text) TO pgbouncer;

Exemples de configurations pour 2 processus PgBouncer en pairage afin de créer une configuration PgBouncer à plusieurs cœurs utilisant so_reuseport. La configuration du premier processus :

[databases]
postgres = host=localhost dbname=postgres

[peers]
1 = host=/tmp/pgbouncer1
2 = host=/tmp/pgbouncer2

[pgbouncer]
listen_addr=127.0.0.1
auth_file=auth_file.conf
so_reuseport=1
unix_socket_dir=/tmp/pgbouncer1
peer_id=1

La configuration du second processus :

[databases]
postgres = host=localhost dbname=postgres

[peers]
1 = host=/tmp/pgbouncer1
2 = host=/tmp/pgbouncer2

[pgbouncer]
listen_addr=127.0.0.1
auth_file=auth_file.conf
so_reuseport=1
; only unix_socket_dir and peer_id are different
unix_socket_dir=/tmp/pgbouncer2
peer_id=2

Voir aussi

pgBouncer(1) - page de manuel pour une utilisation générale, commandes de la console

https://www.pgbouncer.org/