pg_ctl — initialiser, démarrer, arrêter ou contrôler le serveur PostgreSQL
pg_ctl init[db] [-D répertoire_données] [-s] [-o options-initdb]
pg_ctl start [-D répertoire_données] [-l nomfichier] [-W] [-t secondes] [-s] [-o options] [-p chemin] [-c]
pg_ctl stop [-D répertoire_données] [-m
s[mart] | f[ast] | i[mmediate]
] [-W] [-t secondes] [-s]
pg_ctl logrotate [-D répertoire_données] [-s]
pg_ctl restart [-D répertoire_données] [-m
s[mart] | f[ast] | i[mmediate]
] [-W] [-t secondes] [-s] [-o options] [-c]
pg_ctl reload [-D répertoire_données] [-s]
pg_ctl status [-D répertoire_données]
pg_ctl promote [-s] [-D répertoire_données] [-W] [-t secondes] [-s]
pg_ctl kill nom_signal id_processus
Sur Microsoft Windows, également :
pg_ctl register [-D répertoire_données] [-N nom_service] [-U nom_utilisateur] [-P mot_de_passe] [-S
a[uto] | d[emand]
] [-e source] [-W] [-t secondes] [-s] [-o options]
pg_ctl unregister [-N nom_service]
pg_ctl est un outil qui permet d'initialiser une instance, de démarrer, d'arrêter, ou de redémarrer une instance PostgreSQL (postgres). Il permet également d'afficher le statut d'une instance en cours d'exécution.
Bien que le serveur puisse être démarré manuellement, pg_ctl encapsule les tâches comme la redirection des traces ou le détachement du terminal et du groupe de processus. Il fournit également des options intéressantes pour contrôler l'arrêt.
Le mode init ou initdb crée une nouvelle
instance PostgreSQL. Une instance est un
ensemble de bases contrôlées par une même instance du serveur. Ce mode
invoque la commande initdb. Voir initdb pour les détails.
Le mode start lance une nouvelle instance. Le serveur est
démarré en tâche de fond et l'entrée standard est attachée à
/dev/null (sur nul sur Windows).
Sur les systèmes Unix, par défaut, la sortie standard et la sortie des
erreurs du serveur sont envoyées sur la sortie standard de
pg_ctl (pas la sortie des erreurs). La sortie
standard de pg_ctl devrait ensuite être
redirigée dans un fichier standard ou dans un fichier pipe vers un autre
processus comme un outil de rotation de fichiers de trace comme
rotatelogs. Dans le cas contraire,
postgres écrira sa sortie sur le terminal de contrôle.
Sur Windows, par défaut, la sortie standard et la sortie des erreurs du
serveur sont envoyées au terminal. Les comportements par défaut peuvent
être changés en utilisant l'option -l pour rediriger la
sortie du serveur dans un fichier de trace. L'utilisation de l'option
-l ou d'une redirection de la sortie est recommandée.
Le mode stop arrête le serveur en cours d'exécution dans
le répertoire indiqué. Trois méthodes différentes d'arrêt peuvent être
choisies avec l'option -m : le mode
« smart » désactive les nouvelles connexions, puis attend la
déconnexion de tous les clients et la fin de la sauvegarde en ligne (PITR).
Si le serveur est en mode hot standby, la
récupération et la réplication en continu sont arrêtées dès que tous les
clients se sont déconnectés. Le mode « fast » (la valeur par
défaut) n'attend pas la déconnexion des clients et stoppe la sauvegarde en
ligne (PITR). Toutes les transactions actives sont annulées et les clients
sont déconnectés. Le serveur est ensuite arrêté. Le mode
« immediate » tue tous les processus serveur immédiatement, sans
leur laisser la possibilité de s'arrêter proprement. Ce choix conduit à une
phase de récupération au redémarrage.
Le mode restart exécute un arrêt suivi d'un démarrage.
Ceci permet de modifier les options en ligne de commande de
postgres, ou de changer des options du fichier de
configuration qui ne peuvent pas être modifiées sans un redémarrage du
serveur. Si des chemins relatifs sont utilisés sur la ligne de commande
durant le redémarrage du serveur, restart pourrait échouer
à moins que pg_ctl ne soit exécuté depuis le
même répertoire courant que celui durant le démarrage du serveur.
Le mode reload envoie simplement au processus
postgres un signal SIGHUP. Le
processus relit alors ses fichiers de configuration
(postgresql.conf, pg_hba.conf,
etc.). Cela permet de modifier les options des fichiers de configuration
qui ne requièrent pas un redémarrage complet pour être prises en compte.
Le mode status vérifie si un serveur est toujours en cours
d'exécution sur le répertoire de données indiqué. Si c'est le cas, le
PID du serveur et les options en ligne de commande
utilisées lors de son démarrage sont affichés. Si le serveur n'est pas en
cours d'exécution, pg_ctl retourne une valeur de
sortie de 3. Si un répertoire de données accessible n'est pas indiqué,
pg_ctl retourne une valeur de sortie de 4.
Le mode promote commande au serveur secondaire en cours
d'exécution dans le répertoire de données spécifié d'arrêter le mode de
secours et de commencer des opérations en lecture / écriture.
Le mode logrotate effectue une rotation du fichier de
traces du serveur. Pour les détails de l'utilisation de ce mode avec les
outils externes de rotation de traces, voir Section 25.3.
Le mode kill envoie un signal à un processus spécifique.
Ceci est particulièrement utile pour Microsoft
Windows, qui ne possède pas de commande
kill. --help permet
d'afficher la liste des noms de signaux supportés.
Le mode register enregistre le serveur
PostgreSQL comme service système sur
Microsoft Windows. L'option -S
permet la sélection du type de démarrage du service, soit
« auto » (lance le service automatiquement lors du démarrage du
serveur) soit « demand » (lance le service à la demande).
Le mode unregister supprime l'enregistrement du service
système sur Microsoft Windows. Ceci annule les
effets de la commande register.
-c--core-filesTente d'autoriser la création de fichiers core suite à un arrêt brutal du serveur, sur les plateformes où cette fonctionnalité est disponible, en augmentant la limite logicielle qui en dépend. C'est utile pour le déboguage et pour diagnostiquer des problèmes en permettant la récupération d'une trace de la pile d'un processus serveur en échec.
-D répertoire_données--pgdata=datadir
Indique l'emplacement des fichiers de configuration de la base de
données sur le système de fichiers. Si cette option est omise, la
variable d'environnement PGDATA est utilisée.
-l nom_fichier--log=nom_fichier
Ajoute la sortie des traces du serveur dans
nom_fichier. Si le fichier n'existe pas, il
est créé. L'umask est configuré à 077, donc
l'accès au journal des traces est, par défaut, interdit aux autres
utilisateurs.
-m mode--mode=mode
Précise le mode d'arrêt. mode peut valoir
smart, fast ou
immediate, ou la première lettre d'un de ces trois
mots. Si cette option est omise, fast est utilisé.
-o options_initdb--options=options_initdb
Indique les options à passer directement à la commande
postgres. -o peut être utilisé
plusieurs fois, et toutes les options spécifiées seront transférées.
Les options_initdb doivent habituellement
être entourées de guillemets simples ou doubles pour s'assurer qu'elles
sont bien passées comme un groupe.
-p chemin
Indique l'emplacement de l'exécutable postgres. Par
défaut, l'exécutable postgres est pris à partir du
même répertoire que pg_ctl ou, si cela échoue, à
partir du répertoire d'installation codé en dur. Il n'est pas nécessaire
d'utiliser cette option sauf cas inhabituel, comme lorsque des erreurs
concernant l'impossibilité de trouver l'exécutable
postgres apparaissent.
Dans le mode init, cette option indique de manière
analogue la localisation de l'exécutable initdb.
-s--silentAffichage des seules erreurs, pas de messages d'information.
-t secondes--timeout=secondes
Spécifie le nombre maximal de secondes à attendre lors de l'attente de
la fin d'une opération (voir l'option -w). La valeur
par défaut est la valeur de la variable d'environnement
PGCTLTIMEOUT, ou 60 secondes si cette variable n'est pas
positionnée.
-V--versionAffiche la version de pg_ctl, puis quitte.
-w--wait
Attend la fin de l'opération. Cela est supporté pour les modes
start, stop,
restart, promote, et
register, et il s'agit de la valeur par défaut pour
ces modes.
Lors d'une attente, pg_ctl tente de façon répétée de
vérifier le fichier PID du serveur, s'endormant pour
un court instant entre chaque test. Le démarrage est considéré réalisé
quand le fichier PID indique que le serveur est prêt
à accepter des connexions. L'arrêt est considéré réalisé quand le
serveur a supprimé le fichier PID. Cette option
permet d'entrer une passphrase SSL au démarrage.
pg_ctl renvoie un code d'erreur basé sur le succès du
démarrage ou de l'arrêt.
Si l'opération ne se termine pas dans le délai configuré (voir l'option
option -t), alors pg_ctl quitte avec
un code de sortie différent de zéro. Mais notez que l'opération pourrait
continuer en tâche de fond et finalement réussir.
-W--no-wait
N'attend pas la fin de l'opération. Il s'agit de l'opposé de l'option
-w.
Si l'attente est désactivée, l'action demandée est déclenchée, mais il n'y a aucun retour sur son succès. Dans ce cas, le fichier de trace du serveur ou un système de supervision extérieur devra être utilisé pour vérifier le progrès et le succès de l'opération.
Dans les précédentes versions de PostgreSQL, c'était le comportement par
défaut, sauf pour le mode stop.
-?--helpAffiche de l'aide sur les arguments en ligne de commande de pg_ctl, puis quitte.
Si une option spécifiée est valide mais n'est pas applicable pour le mode d'opération sélectionné, pg_ctl l'ignore.
-e source
Nom de la source d'événement à utiliser par
pg_ctl pour tracer dans le journal des
événements lors de l'utilisation d'un service Windows. La valeur par
défaut est PostgreSQL. Notez que ceci ne contrôle
que les messages envoyés par pg_ctl ;
une fois démarré, le serveur utilise la source d'événement spécifiée
par son paramètre event_source. Si le serveur
échoue très tôt durant le démarrage, avant que ce paramètre n'ait été
positionné, il pourrait également envoyer une trace avec le nom de la
source d'événement par défaut PostgreSQL.
-N nom_service
Nom du service système à enregistrer. Ce nom est utilisé à la fois
comme nom de service et comme nom affiché. La valeur par défaut est
PostgreSQL.
-P mot_de_passeMot de passe de l'utilisateur qui exécute le service.
-S start-type
Type de démarrage du service système à enregistrer.
start-type peut valoir
auto ou demand ou la première
lettre de ces deux possibilités. Si cette option est omise, la valeur
par défaut est auto.
-U nom_utilisateur
Nom de l'utilisateur qui exécute le service. Pour les utilisateurs
identifiés sur un domaine, on utilise le format
DOMAINE\nom_utilisateur.
PGCTLTIMEOUTLimite par défaut du nombre de secondes à attendre pour la fin de l'opération de démarrage ou d'arrêt. Si elle n'est pas configurée, l'attente est de 60 secondes.
PGDATAEmplacement par défaut du répertoire des données.
La plupart des mode pg_ctl requièrent de connaitre
l'emplacement du répertoire de donnée ; par conséquence, l'option
-D est nécessaire à moins que PGDATA ne
soit positionné.
Pour des variables serveurs supplémentaires qui affectent le serveur, voir postgres.
postmaster.pidpg_ctl examine ce fichier dans le répertoire de données pour déterminer si le serveur est actuellement en cours d'exécution.
postmaster.opts
Si ce fichier existe dans le répertoire des données,
pg_ctl (en mode restart)
passe le contenu du fichier comme options de
postgres, sauf en cas de surcharge par
l'option -o. Le contenu de ce fichier est aussi affiché
en mode status.
Démarrer un serveur, avec blocage tant que le serveur n'est pas complètement démarré :
$pg_ctl start
Pour exécuter le serveur en utilisant le port 5433, et en s'exécutant sans
fsync :
$pg_ctl -o "-F -p 5433" start
Pour arrêter le serveur, utilisez :
$pg_ctl stop
L'option -m autorise le contrôle sur la façon dont le
serveur est arrêté :
$pg_ctl stop -m smart
Redémarrer le serveur est pratiquement équivalent à l'arrêter puis à le
démarrer à nouveau si ce n'est que, par défaut, pg_ctl
sauvegarde et réutilise les options en ligne de commande qui étaient
passées à l'instance précédente. Pour redémarrer le serveur de la façon la
plus simple, on utilise :
$pg_ctl restart
Mais si -o est spécifié, cela remplace toute option
précédente. Redémarrer en utilisant le port 5433 et en désactivant
fsync après redémarrage :
$pg_ctl -o "-F -p 5433" restart
Exemple de statut affiché à partir de pg_ctl :
$pg_ctl statuspg_ctl: server is running (PID: 13718) /usr/local/pgsql/bin/postgres "-D" "/usr/local/pgsql/data" "-p" "5433" "-B" "128"
La deuxième ligne est la ligne de commande qui sera appelée en mode redémarrage.