O pg_ctl é um utilitário para iniciar, parar ou reiniciar o postmaster, o servidor PostgreSQL, ou exibir o status de um postmaster ativo. Embora o postmaster possa ser iniciado manualmente, o pg_ctl encapsula tarefas como redirecionar a saída do log, desconectar do terminal e do grupo de processo de maneira adequada, além de fornecer opções convenientes para uma parada controlada.
No modo iniciar (start), um novo postmaster é lançado. O servidor inicia em segundo plano, e a entrada padrão lê de /dev/null. A saída padrão e o erro padrão são ambos adicionados a um arquivo de log, se a opção -l for usada, ou são redirecionados para a saída padrão do pg_ctl (não o erro padrão). Se o arquivo de log não for definido, a saída padrão do pg_ctl deve ser redirecionada para um arquivo ou ser enviada para outro processo (através de um pipe) como, por exemplo, para um programa para rotação de logs, senão o postmaster vai escrever sua saída no terminal de controle (do segundo plano) e não vai se desconectar do grupo de processo da shell.
No modo parar (stop), o postmaster que está executando no diretório de dados especificado é parado. Três métodos diferentes de parada podem ser selecionados pela opção -m: O modo "Smart" (inteligente) aguarda todos os clientes se desconectarem. Este é o modo padrão. O modo "Fast" (rápido) não aguarda os clientes se desconectarem. Todas as transações ativas são desfeitas (rollback), os clientes são desconectados à força e, em seguida, o servidor é parado. O modo "Immediate" (imediato) aborta todos os processor servidores sem executar uma parada limpa, obrigando um processamento de recuperação ao reiniciar.
O modo reiniciar (restart) executa uma parada seguida por um início. Permite mudar as opções de linha de comando do postmaster.
O modo recarregar (reload) simplesmente envia o sinal SIGHUP para o postmaster, fazendo com que este releia os arquivos de configuração (postgresql.conf, pg_hba.conf, etc.). Permite mudar as opções do arquivo de configuração que não requerem um reinício completo para ter efeito.
O modo status verifica se o postmaster está executando e, se estiver, exibe o PID e as opções de linha de comando que foram usadas para chamá-lo.
Especifica a localização dos arquivos de banco de dados. Se for omitido, a variável de ambiente PGDATA é usada.
Apensa a saída do log do servidor ao nome_do_arquivo. Se o arquivo não existir é criado. A umask é definida como 077, não permitindo o acesso ao arquivo de log pelos outros usuários por padrão.
Especifica o modo de parar (shutdown). O modo pode ser smart, fast ou immediate, ou a primeira letra de um desses três.
Especifica opções a serem passadas diretamente para o postmaster.
Os parâmetros são geralmente envoltos por aspas(") ou apóstrofos (') para garantir que são passados como um grupo.
Especifica a localização do arquivo executável postmaster. Por padrão o postmaster é pego do mesmo diretório do pg_ctl ou, se falhar, do diretório de instalação. Não é necessário usar esta opção a menos que esteja se fazendo algo diferente do usual e recebendo uma mensagem de erro informando que o postmaster não foi encontrado.
Mostra somente os erros, sem nenhuma mensagem informativa.
Aguarda o início ou a parada terminar. Espera no máximo 60 segundos. Este é o padrão para a parada.
Não aguarda o início ou a parada terminar. Este é o padrão para o início e o reínicio.
Para iniciar o postmaster:
$ pg_ctl start
Exemplo de iniciar o postmaster, bloqueando até que o postmaster esteja ativo:
$ pg_ctl -w start
Para iniciar o postmaster utilizando a porta 5433 e executando sem o fsync pode-se usar:
$ pg_ctl -o "-F -p 5433" start
$ pg_ctl stop
pára o postmaster. A chave -m permite controlar como o servidor vai parar.
Praticamente equivale a parar o postmaster e iniciá-lo novamente, exceto que o pg_ctl salva e reutiliza as opções de linha de comando que foram passadas para a instância executando anteriormente. Para reiniciar o postmaster da forma mais simples possível:
$ pg_ctl restart
Para reiniciar o postmaster, aguardando o término da parada e da inicialização:
$ pg_ctl -w restart
Para reiniciar usando a porta 5433 e desativando o fsync após o reinício:
$ pg_ctl -o "-F -p 5433" restart
Abaixo segue uma um exemplo da saída de status mostrada pelo pg_ctl:
$ pg_ctl status pg_ctl: postmaster is running (pid: 13718) Command line was: /usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
Esta é a linha de comandos que seria usada no modo de reinício.