Descrição

O pg_ctl é um utilitário para inicializar um agrupamento de bancos de dados do PostgreSQL, iniciar, parar ou reiniciar o servidor de banco de dados PostgreSQL (postgres), ou mostrar o status de um servidor em execução. Embora o servidor possa ser iniciado manualmente, o pg_ctl encapsula tarefas como redirecionar a saída do registro de transações (log), e desanexar adequadamente do terminal e do grupo de processos. Também oferece opções convenientes para uma paralisação controlada.

O modo init ou initdb cria um novo agrupamento de bancos de dados do PostgreSQL, ou seja, uma coleção de bancos de dados gerenciados por uma única instância do servidor. Este modo chama o comando initdb. Veja initdb para obter detalhes.

O modo start inicia um servidor. O servidor é iniciado em segundo plano, e sua entrada padrão é anexada a /dev/null (ou nul, no Windows). Em sistemas do tipo Unix, por padrão, as saídas padrão (STDOUT) e de erro padrão (STDERR) do servidor são enviadas para a saída padrão do pg_ctl (e não para a saída de erro padrão). A saída padrão do pg_ctl deverá então ser redirecionada para um arquivo, ou canalizada para outro processo, como um programa de rotação de registro de transações, como o rotatelogs; caso contrário, o postgres irá escrever sua saída no terminal de controle (do segundo plano), não se desligando do grupo de processos do interpretador de comandos (shell). No Windows, por padrão, as saídas padrão e de erro padrão do servidor são enviadas para o terminal. Estes comportamentos padrão podem ser alterados usando a opção -l para anexar a saída do servidor a um arquivo de registro de transações. O uso da opção -l, ou o redirecionamento da saída, é recomendado.

O modo stop para o servidor que está sendo executado no diretório de dados especificado. Podem ser selecionados três métodos diferentes de paralisação usando a opção -m. O modo “Smart” (inteligente) impede novas conexões e, em seguida, aguarda que todos os clientes se desconectem. Se o servidor estiver em modo de espera ativa, a recuperação e a replicação por fluxo serão encerradas assim que todos os clientes se desconectarem. O modo “Fast” (rápido) (o padrão) não espera que os clientes se desconectem. Todas as transações ativas são desfeitas, os clientes são desconectados à força e, em seguida, o servidor é parado. O modo “Immediate” (imediato) interrompe todos os processos do servidor imediatamente, sem realizar uma paralisação limpa. Esta escolha levará a um ciclo de recuperação de falha durante a próxima ativação do servidor.

O modo restart efetivamente executa uma paralisação seguida de um início. Permite alterar as opções de linha de comando do postgres, ou alterar as opções do arquivo de configuração que não podem ser alteradas sem reiniciar o servidor. Se foram usados caminhos relativos na linha de comando durante a ativação do servidor, o restart poderá falhar, a menos que o pg_ctl seja executado no mesmo diretório onde se encontrava durante a ativação do servidor.

O modo reload (recarga) simplesmente envia ao processo servidor do postgres o sinal SIGHUP, fazendo com que este leia novamente seus arquivos de configuração (postgresql.conf, pg_hba.conf, etc.). Permite alterar as opções do arquivo de configuração que não requerem um reinício completo do servidor para entrar em vigor.

O modo status verifica se algum servidor está sendo executado no diretório de dados especificado. Se estiver, serão mostrados o PID do servidor, e as opções de linha de comando usadas para chamá-lo. Se o servidor não estiver em execução, o pg_ctl irá retornar um status de saída igual a 3. Se não for especificado um diretório de dados acessível, o pg_ctl irá retornar um status de saída igual a 4.

O modo promote (promover) comanda o servidor em espera, que está em execução no diretório de dados especificado, para encerrar o modo de espera e iniciar as operações de leitura/escrita.

O modo logrotate efetua uma rotação no arquivo de registro de transações do servidor. Para obter detalhes sobre como usar este modo com ferramentas externas de rotação do registro de transações, veja Manutenção de arquivo de registro.

O modo kill envia um sinal para o processo especificado. Serve principalmente para o Microsoft Windows, que não possui o comando kill nativo. Deve ser usado --help para ver a lista de nomes de sinais com suporte.

O modo register registra o servidor PostgreSQL como um serviço do sistema no Microsoft Windows. A opção -S permite a seleção do tipo de início do serviço, seja “auto” (inicia o serviço automaticamente na carga do sistema operacional), ou “demand” (inicia o serviço sob demanda).

O modo unregister remove o registro do serviço do sistema no Microsoft Windows. Desfaz os efeitos do comando register.

Opções

Se for especificada uma opção válida, mas não relevante para o modo de operação selecionado, o pg_ctl irá ignorá-la.

Variáveis de ambiente

A maioria dos modos do pg_ctl requer o conhecimento da localização do diretório de dados; portanto, a opção -D é necessária, a menos que PGDATA esteja definida.

Para variáveis adicionais que afetam o servidor, veja postgres.

Arquivos

Exemplos

$ pg_ctl start
# ou no Debian 12 (N. T.)
$ sudo systemctl start postgresql@18-main

$ pg_ctl -o "-F -p 5433" start

$ pg_ctl stop
# ou no Debian 12 (N. T.)
$ sudo systemctl stop postgresql@18-main

$ pg_ctl stop -m smart

$ pg_ctl restart
# ou no Debian 12 (N. T.)
$ sudo systemctl restart postgresql@18-main

$ pg_ctl -o "-F -p 5433" restart

$ sudo su - postgres
$ /usr/lib/postgresql/18/bin/pg_ctl status -D /var/lib/postgresql/18/main/
pg_ctl: servidor está executando (PID: 8700)
/usr/lib/postgresql/18/bin/postgres \
"-D" "/var/lib/postgresql/18/main" \
"-c" "config_file=/etc/postgresql/18/main/postgresql.conf"

Veja também