Documentation PostgreSQL 15.15 » Administration du serveur » Configuration du serveur » Paramètres de configuration

Précédent | Niveau supérieur | Suivant
Chapitre 20. Configuration du serveur | Sommaire | 20.2. Emplacement des fichiers

## 20.1. Paramètres de configuration

### 20.1.1. Noms et valeurs des paramètres

Tous les noms de paramètres sont insensibles à la casse. Chaque paramètre prend une valeur d'un de ces cinq types : booléen, chaîne de caractères, entier, nombre à virgule flottante ou énumération(enum). Le type détermine la syntaxe pour configurer le paramètre :

- Booléen : les valeurs peuvent être écrites sous les formes `on`, `off`, `true`, `false`, `yes`, `no`, `1`, `0` (toutes insensibles à la casse) ou tout préfixe non ambigu basé sur un d'entre eux.

- Chaîne de caractères : En général, entoure la valeur de guillemets simples, doublant tout guillemet simple compris dans la valeur. Les guillemets peuvent habituellement être omis si la valeur est un nombre ou un identifiant simple. (Les valeurs qui correspondent à un mot clé SQL nécessitent d'être mises (entre guillemets dans certains contextes.)

- Numérique (entier ou nombre à virgule flottante) : les paramètres numériques peuvent être indiqués au format entier ou virgule flottante ; dans ce dernier cas, la valeur est arrondie à l'entier le plus proche si le paramètre est de type entier. Les paramètres de type entier acceptent en plus une valeur hexadécimale (commençant par `0x`) et une valeur octale (commençant par `0`), mais ces formats n'ont pas de virgule flottante. Ne pas utiliser de séparateurs pour les milliers. Les guillemets ne sont pas requis en dehors du format hexadécimal.

- Numérique avec unité : Quelques paramètres numériques ont une unité implicite car elles décrivent des quantités de mémoire ou de temps. L'unité pourra être des octets, des kilo-octets, des blocs (généralement 8 ko), des millisecondes, des secondes ou des minutes. Une valeur numérique sans unité pour un de ces paramètres utilisera l'unité par défaut du paramètre, qui est disponible dans le champ `pg_settings`.`unit`. Pour plus de facilité, les valeurs de certains paramètres peuvent se voir ajouter une unité explicitement, par exemple `'120 ms'` pour une valeur d'intervalle, et elles seront automatiquement converties suivant l'unité par défaut du paramètre. Notez que la valeur doit être écrite comme une chaîne de caractères (avec des guillemets) pour utiliser cette fonctionnalité. Le nom de l'unité est sensible à la casse, et il peut y avoir des espaces blancs entre la valeur numérique et l'unité.

  - Les unités valides de mémoire sont `B` (octets), `kB` (kilo-octets), `MB` (méga-octets), `GB` (giga-octets) et `TB` (téra-octets). Le multiplieur pour les unités de mémoire est 1024, et non pas 1000.

  - Les unités valides d'intervalle sont `us` (microsecondes), `ms` (millisecondes), `s` (secondes), `min` (minutes), `h` (heures) et `d` (jours).

  Si une valeur à virgule flottante est indiquée avec une unité, elle sera arrondie au multiple de la prochaine unité la plus petite. Par exemple, `30.1 GB` sera convertie en `30822 MB`, et non pas `32319628902 B`. Si le paramètre est de type entier, un arrondissement final en entier survient après toute conversion d'unité.

- Énuméré : Les valeurs des paramètres de type énuméré sont écrits de la même façon que les valeurs des paramètres de type chaînes de caractères mais sont restreintes à un ensemble limité de valeurs. Les valeurs autorisées d'un paramètre spécifique sont disponibles dans le champ `pg_settings`.`enumvals`. Les valeurs des paramètres de type énuméré ne sont pas sensibles à la casse.

### 20.1.2. Interaction avec les paramètres via le fichier de configuration

La façon fondamentale de configurer les paramètres est d'éditer le fichier `postgresql.conf`, qui est normalement conservé dans le répertoire des données. Une copie par défaut est installé dans le répertoire de l'instance lors de l'initialisation. Un exemple de contenu peut être :

    # Ceci est un commentaire
    log_connections = yes
    log_destination = 'syslog'
    search_path = '"$user", public'
    shared_buffers = 128MB

Un paramètre est indiqué par ligne. Le signe égal entre le nom et la valeur est optionnel. Les espaces n'ont pas de signification (sauf à l'intérieur d'une valeur entre guillemets) et les lignes vides sont ignorées. Les symboles dièse (`#`) désignent le reste de la ligne comme un commentaire. Les valeurs des paramètres qui ne sont pas des identificateurs simples ou des nombres doivent être placées entre guillemets simples. Pour intégrer un guillemet simple dans la valeur d'un paramètre, on écrit soit deux guillemets (c'est la méthode préférée) soit un antislash suivi du guillemet. Si le fichier contient plusieurs entrées pour le même paramètre, elles sont toutes ignorées sauf la dernière.

Les paramètres configurés de cette façon fournissent des valeurs par défaut pour l'instance. Le paramétrage considéré par les sessions actives sera ces valeurs sauf si elles sont surchargées. Les sections suivantes décrivent les différentes façons dont bénéficient l'administrateur et l'utilisateur pour surcharger les valeurs par défaut.

Il existe aussi une directive `include_if_exists`, qui agit de la même façon que la directive `include`, sauf si le fichier n'existe pas ou ne peut pas être lu. La directive `include` traitera cela comme une erreur, mais la directive `include_if_exists` tracera cet événement et continuera le traitement du fichier de configuration.

Le fichier de configuration est relu à chaque fois que le processus principal du serveur reçoit un signal SIGHUP ; ce signal est facilement envoyé en exécutant `pg_ctl reload` sur la ligne de commande shell ou en appelant la fonction SQL `pg_reload_conf()`. Le processus principal propage aussi ce signal aux processus serveurs en cours d'exécution, pour que les sessions existantes récupèrent aussi les nouvelles valeurs (ceci survient après qu'elles aient terminées d'exécuter la commande en cours d'exécution pour le client). Il est aussi possible d'envoyer le signal à un processus serveur directement. Certains paramètres ne sont pris en compte qu'au démarrage du serveur ; tout changement de ces paramètres dans le fichier de configuration sera ignoré jusqu'au redémarrage du serveur. Les configurations invalides de paramètres sont aussi ignorées (mais tracées) lors du traitement du signal SIGHUP.

En plus du fichier `postgresql.conf`, un répertoire des données d'un serveur PostgreSQL contient un fichier `postgresql.auto.conf` , qui a le même format que le fichier `postgresql.conf`. Cependant, il a pour but d'être édité automatiquement et non pas manuellement. Ce fichier contient les configurations réalisées avec la commande `ALTER SYSTEM`. Ce fichier est lu quand le fichier `postgresql.conf` et lu, et son contenu prend effet de la même façon. Les paramètres configurés dans `postgresql.auto.conf` surchargent ceux configurés dans `postgresql.conf`.

Des outils externes peuvent aussi modifier `postgresql.auto.conf`. Il n'est pas recommandé de le faire alors que le serveur est en cours d'exécution car une commande `ALTER SYSTEM` exécutée en même temps pourrait écraser d'autres modifications. De tels outils devraient simplement ajouter les nouveaux paramètres à la fin ou ils pourraient choisir de supprimer les paramètres dupliqués et/ou supprimer les commentaires (comme le fait `ALTER SYSTEM`).

La vue système `pg_file_settings` peut être utile pour tester par avance des modifications dans les fichiers de configuration, ou pour diagnostiquer des problèmes si un signal SIGHUP n'a pas eu les effets désirés.

### 20.1.3. Interaction avec les paramètres via SQL

PostgreSQL fournit trois commandes SQL pour établir les valeurs par défaut de la configuration. La première, déjà mentionnée, est la commande `ALTER SYSTEM`. Elle fournit un moyen accessible via le SQL pour modifier les valeurs globales par défaut ; c'est l'équivalent fonctionnel de l'édition manuelle du fichier `postgresql.conf`. Il existe aussi deux commandes qui permettent la configuration des valeurs par défaut par base de données et par rôle :

- La commande `ALTER DATABASE` permet de surcharger le paramétrage global suivant la base de connexion.

- La commande `ALTER ROLE` permet de surcharger le paramétrage global suivant la base et l'utilisateur de connexion.

Les paramètres configurés avec `ALTER DATABASE` et `ALTER ROLE` sont appliqués seulement lors du démarrage d'une nouvelle session. Ils surchargent les valeurs obtenues dans les fichiers de configuration ou sur la ligne de commande du lancement du serveur. Ils constituent les valeurs par défaut pour le reste de la session. Notez que certains paramétrages ne peuvent pas être modifiés après le démarrage du serveur, et ne peuvent donc pas être configurés avec ces commandes (ou celles citées ci-dessous).

Une fois qu'un client est connecté à la base de données, PostgreSQL fournit deux commandes SQL supplémentaires (et fonctions équivalentes) pour interagir avec les paramètres de configuration de la session :

- La commande `SHOW` autorise l'inspection de la valeur actuelle de tous les paramètres. La fonction SQL correspondante est `current_setting(setting_name text)` (voir Section 9.27.1).

- La commande `SET` permet la modification de la valeur actuelle de certains paramètres qui peuvent être configurés localement pour une session. Elle n'a pas d'effet sur les autres sessions. Beaucoup de paramètres peuvent être configurés de cette façon par un utilisateur, mais certains peuvent seulement être configurés par des superutilisateurs et des utilisateurs qui ont reçu les droits `SET` sur ces paramètres. La fonction SQL correspondante est `set_config(setting_name, new_value, is_local)` (voir Section 9.27.1).

De plus, la vue système `pg_settings` peut être utilisée pour visualiser et modifier les valeurs locales à la session :

- Exécuter une requête sur cette vue est similaire à l'utilisation de la commande `SHOW ALL`. Cependant, elle fournit plus de détails et est beaucoup plus flexible, vu qu'il est possible d'ajouter des conditions de filtre et des jointures vers d'autres relations.

- Utiliser `UPDATE` sur cette vue, pour mettre à jour la colonne `setting`, est équivalent à exécuter la commande `SET`. Par exemple, l'équivalent de

       SET paramètre_configuration TO DEFAULT;

  est :

       UPDATE pg_settings SET setting = reset_val WHERE name = 'paramètre_configuration';

### 20.1.4. Interaction avec les paramètre via le shell

En plus de pouvoir configurer les valeurs globales des paramètres et d'attacher une configuration spécifique aux bases et aux rôles, vous pouvez fournir un paramétrage à PostgreSQL via des options du shell. Le serveur et la bibliothèque client libpq acceptent des valeurs de paramètres via le shell.

- Lors du démarrage du serveur, des configurations de paramètres peuvent être passées à la commande `postgres` via le paramètre en ligne de commande `-c`. Par exemple,

      postgres -c log_connections=yes -c log_destination='syslog'

  Les paramétrages réalisés de cette façon surchargent ceux fournis dans le fichier `postgresql.conf` ou via la commande `ALTER SYSTEM`, donc ils ne peuvent pas être changés globalement sans redémarrer le serveur.

- Lors du démarrage d'une session client via libpq, un paramétrage peut être spécifié en utilisant la variable d'environnement `PGOPTIONS`. Le paramétrage établi ainsi constitue des valeurs par défaut pour la durée de la session, mais n'affecte pas les autres sessions. Pour des raisons historiques, le format de `PGOPTIONS` est similaire à celui utilisé lors du lancement de la commande `postgres`. Spécifiquement, l'option `-c` doit être indiquée. Par exemple :

      env PGOPTIONS="-c geqo=off -c statement_timeout=5min" psql

  Les autres clients et autres bibliothèques peuvent fournir leur propres mécanismes via la shell ou autrement, pour permettre à l'utilisateur de modifier le paramétrage de la session sans avoir à utiliser des commandes SQL.

### 20.1.5. Gestion du contenu des fichiers de configuration

PostgreSQL fournit plusieurs fonctionnalités pour diviser le fichier de configuration `postgresql.conf` en plusieurs sous-fichiers. Ces fonctionnalités sont tout particulièrement utiles quand plusieurs serveurs sont à gérer alors qu'ils partagent une partie de la configuration.

En plus des paramètres, le fichier `postgresql.conf` peut contenir des directives d'inclusion, qui précisent les autres fichiers à lire et à traiter comme s'ils étaient insérés dans le fichier de configuration à cet emplacement. Cette fonctionnalité permet de diviser un fichier de configuration en plusieurs parties séparées. Les directives d'inclusion ressemblent à :

    include 'nom_fichier'

Si le nom du fichier n'est pas un chemin absolu, il est considéré comme relatif au répertoire contenant le fichier de configuration de référence. Les inclusions peuvent être imbriquées.

Il existe aussi une directive `include_if_exists` qui agit de la même façon que la directive `include` sauf si le fichier référencé n'existe pas ou ne peut pas être lu. La directive `include` considère ces états comme une condition d'erreur mais `include_if_exists` ne fait que tracer un message et continue le traitement du fichier de configuration de référence.

Le fichier `postgresql.conf` peut aussi contenir `include_dir directives`, qui précise un répertoire entier de fichiers de configuration à inclure. Il s'utilise de la même façon :

     include_dir 'répertoire'

Les noms de répertoire relatifs sont pris comme ayant comme base le répertoire du fichier de configuration. Dans ce répertoire spécifique, seuls les fichiers dont le nom finit avec le suffixe `.conf` seront inclus. Les noms de fichiers qui commencent avec le caractère `.` sont aussi ignorés, pour éviter des erreurs vu que ces fichiers sont cachés sur certaines plateformes. Plusieurs fichiers dans un répertoire d'inclusion sont traités dans l'ordre des noms de fichiers (d'après les règles de la locale C, autrement dit les numéros avant les lettres, et les majuscules avant les minuscules).

Les fichiers et répertoires inclus peuvent être utilisés pour séparer logiquement les portions de la configuration de la base de données, plutôt que d'avoir un gigantesque fichier `postgresql.conf`. Songez à une société qui a deux serveurs de bases de données, chacun avec une quantité de mémoire différente. Il existe vraisemblablement des éléments de la configuration qui vont être partagés entre les deux serveurs, comme par exemple la configuration des traces. Mais les paramètres relatifs à la mémoire sur le serveur varieront entre les deux. Et il pourrait aussi y avoir une personnalisation des serveurs. Une façon de gérer cette situation est de casser les changements de configuration en trois fichiers. Vous pouvre ajouter cela à la fin de votre fichier `postgresql.conf` pour les inclure :

     include 'commun.conf'
     include 'memoire.conf'
     include 'serveur.conf'

Tous les systèmes auraient le même `commun.conf`. Chaque serveur avec une quantité particulière de mémoire pourrait partager le même `memory.conf`. Vous pourriez en avoir un pour tous les serveurs disposant de 8 Go de RAM, un autre pour ceux ayant 16 Go. Enfin, `serveur.conf` pourrait avoir les configurations réellement spécifiques à un serveur.

Une autre possibilité revient à créer un répertoire de fichiers de configuration et de placer les fichiers dans ce répertoire. Par exemple, un répertoire `conf.d` pourrait être référencé à la fin du `postgresql.conf` :

     include_dir 'conf.d'

Ensuite, vous pourriez renommer les fichiers dans le répertoire `conf.d` de cette façon :

     00commun.conf
     01memoire.conf
     02serveur.conf

Cette convention de nommage établit un ordre clair dans lequel ces fichiers sont chargés. C'est important parce que seul le dernier paramétrage d'un paramètre particulier sera utilisé lors de la lecture de la configuration par le serveur. Dans cet exemple, un paramètre configuré dans `conf.d/02server.conf` surchargera la configuration du même paramètre dans `conf.d/01memory.conf`.

Vous pouvez utiliser à la place cette approche pour nommer les fichiers de façon claire :

     00commun.conf
     01memoire-8Go.conf
     02serveur-truc.conf

Ce type d'arrangement donne un nom unique pour chaque variation du fichier de configuration. Ceci peut aider à éliminer l'ambiguïté quand plusieurs serveurs ont leur configuration stockée au même endroit, par exemple dans un dépôt de contrôle de version. (Stocker les fichiers de configuration de la base avec un outil de contrôle de version est une autre bonne pratique à considérer.)