Documentation PostgreSQL 14.22 » Référence » Applications relatives au serveur PostgreSQL » pg_ctl

Précédent | Niveau supérieur | Suivant
pg_controldata | Sommaire | pg_resetwal

## pg_ctl

pg_ctl — initialiser, démarrer, arrêter ou contrôler le serveur PostgreSQL

## Synopsis

`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`]

## Description

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`.

## Options

`-c`
`--core-files`

  Tente 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`
`--silent`

  Affichage 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`
`--version`

  Affiche 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`.

`-?`
`--help`

  Affiche 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.

### Options Windows

`-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_passe``

  Mot 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`.

## Environnement

`PGCTLTIMEOUT`

  Limite 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.

`PGDATA`

  Emplacement 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.

## Fichiers

`postmaster.pid`

  pg_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`.

## Exemples

### Lancer le serveur

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

### Arrêt du serveur

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émarrage du serveur

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

### Affichage de l'état du serveur

Exemple de statut affiché à partir de pg_ctl :

    $ pg_ctl status

    pg_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.

## Voir aussi

initdb, postgres