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.
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.
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. 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';
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.
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.)