postgres — servidor de banco de dados PostgreSQL
postgres [opção...]
O postgres é o servidor de banco de dados
PostgreSQL.
Para uma aplicação cliente acessar um banco de dados, a aplicação
se conecta (por uma rede, ou localmente) a uma instância
do postgres em execução.
A instância do postgres então inicia um processo
servidor separado para tratar a conexão.
Uma instância do postgres sempre gerencia os dados
de exatamente um agrupamento de bancos de dados.
Um agrupamento de bancos de dados é uma coleção de bancos de dados
armazenados em um local comum do sistema de arquivos
(a “área de dados”).
Pode ser executada mais de uma instância do postgres
em um sistema simultaneamente, desde que usem áreas de dados
e portas de comunicação diferentes (veja abaixo).
Quando o postgres inicia, ele precisa saber a
localização da área de dados.
A localização deve ser especificada pela opção -D, ou
pela variável de ambiente PGDATA; não há valor padrão.
Normalmente, a opção -D, ou a variável de ambiente
PGDATA, apontam diretamente para o diretório da
área de dados criado por initdb.
Outras disposições de arquivo possíveis são discutidas em
Locais dos arquivos.
Por padrão, o postgres inicia em primeiro plano
e escreve as mensagens de registro (log)
na saída de erro padrão.
Em situações práticas, o postgres deve ser
iniciado como um processo em segundo plano, talvez durante a
inicialização do sistema operacional.
O comando postgres também pode ser chamado
no modo mono-usuário.
O uso principal para este modo é durante a inicialização realizada
pelo initdb.
Às vezes, é usado para depuração ou recuperação de desastres;
note-se que a execução de um servidor no modo mono-usuário não é
realmente adequada para depuração do servidor, uma vez que não
haverá nenhuma comunicação entre processos e bloqueio reais.
Quando chamado no modo mono-usuário a partir de uma interface de
comandos (shell), o usuário poderá
inserir consultas e os resultados serão mostrados na tela,
mas de uma forma mais útil para desenvolvedores do que para
usuários finais.
No modo mono-usuário, o usuário da sessão é definido como o
usuário com ID 1, sendo concedidos poderes de superusuário
implícitos a este usuário.
Na verdade, este usuário não precisa existir, portanto, o modo
mono-usuário pode ser usado para recuperar manualmente certos tipos
de danos acidentais aos catálogos do sistema.
O postgres aceita os argumentos
de linha de comando mostrados a seguir.
Para uma discussão detalhada das opções, deve ser consultado
Configuração do servidor.
Pode-se evitar a digitação da maioria dessas opções usando
um arquivo de configuração.
Para atender uma aplicação, também podem ser definidas algumas opções
(seguras) durante a conexão do cliente, que só serão aplicadas
a esta sessão.
Por exemplo, se a variável de ambiente PGOPTIONS
estiver definida, os clientes baseados na libpq
passarão esta cadeia de caracteres para o servidor, que a interpretará
como opções de linha de comando do postgres.
-B nbuffersDefine o número de buffers compartilhados para uso pelos processos servidores. O valor padrão desse parâmetro é escolhido automaticamente pelo initdb. Especificar esta opção equivale a definir o parâmetro de configuração shared_buffers.
-c nome=valor
Define o parâmetro de tempo de execução indicado.
Os parâmetros de configuração aceitos pelo
PostgreSQL são descritos em
Configuração do servidor.
A maioria das outras opções de linha de comando são, na verdade,
formas abreviadas dessa atribuição de parâmetro.
A opção -c pode aparecer várias vezes para
definir vários parâmetros.
-C nome
Retorna o valor do parâmetro de tempo de execução indicado,
e termina.
(Veja a opção -c acima para obter detalhes.)
Retorna valores do arquivo postgresql.conf,
modificados por quaisquer parâmetros fornecidos nesta chamada.
Não reflete os parâmetros fornecidos quando a instância foi iniciada.
Pode ser usada em um servidor em execução para a maioria dos parâmetros. Entretanto, o servidor precisa ser desativado para alguns parâmetros calculados em tempo de execução (por exemplo, shared_memory_size, shared_memory_size_in_huge_pages e wal_segment_size).
Esta opção destina-se a outros programas que interagem com uma instância do servidor, como pg_ctl, para consultar valores de parâmetros de configuração. As aplicações voltados para o usuário devem usar o comando SHOW, ou a visão pg_settings.
-d nível_de_depuração
Define o nível de depuração.
Quanto mais alto este valor for definido, mais saída de depuração
será escrita no registro (log)
do servidor.
Os valores são de 1 a 5.
Também é possível usar -d 0 para uma sessão
específica, impedindo que o nível de depuração do processo
servidor pai postgres seja propagado para
esta sessão.
-D diretório_de_dadosEspecifica o local no sistema de arquivos, dos arquivos de configuração do banco de dados. Veja Locais dos arquivos para obter mais informações.
-e
Define o estilo de data padrão para “European”, que
é a ordem DMY de entrada dos campos de data.
Também faz com que o dia venha antes do mês em determinados
formatos de saída de data.
Veja Tipos de dados de data e hora
para obter mais informações.
-F
Desativa as chamadas a fsync para melhorar
o desempenho, com risco de corrupção de dados em caso de falha
do sistema.
Especificar esta opção equivale a desativar o parâmetro
de configuração fsync.
Leia os detalhes na documentação antes de usar esta opção!
-h nome_do_hospedeiro
Especifica o nome do hospedeiro IP, ou endereço, no qual o
postgres deve escutar as conexões
TCP/IP das aplicações cliente.
O valor também pode ser uma lista de endereços separados por
vírgula, ou * para especificar a escuta
em todas as interfaces disponíveis.
O valor vazio especifica não escutar nenhum endereço de IP,
caso em que apenas os
soquetes de domínio Unix.
podem ser usados para conectar ao servidor.
O padrão é ouvir apenas
localhost.
Especificar esta opção equivale a definir o parâmetro
de configuração listen_addresses.
-i
Permite que clientes remotos se conectem via conexões
TCP/IP (domínio da Internet).
Sem esta opção, são somente aceitas conexões locais.
Esta opção equivale definir
listen_addresses como *
no arquivo postgresql.conf,
ou através da opção -h.
Esta opção está em obsolescência, porque não permite o acesso
a todas as funcionalidades de listen_addresses.
Geralmente é melhor definir listen_addresses
diretamente.
-k diretório
Especifica o diretório do soquete de domínio
Unix no qual o
postgres deve escutar as conexões das
aplicações cliente.
O valor também pode ser uma lista de diretórios separados por
vírgulas.
Um valor vazio especifica não escutar em nenhum soquete de
domínio Unix;
neste caso, podem ser usados apenas soquetes
TCP/IP para conectar ao servidor.
O valor padrão é normalmente /tmp,
mas pode ser alterado no momento da construção.
Especificar esta opção equivale a definir o parâmetro de
configuração unix_socket_directories.
-lHabilita conexões seguras usando SSL. O PostgreSQL deve ter sido compilado com suporte para SSL para que esta opção esteja disponível. Para obter mais informações sobre como usar SSL, veja Conexões TCP/IP seguras com SSL.
-N número_máximo_de_conexõesDefine o número máximo de conexões de cliente que este servidor aceita. O valor padrão desse parâmetro é escolhido automaticamente pelo initdb. Especificar esta opção equivale a definir o parâmetro de configuração max_connections.
-p porta
Especifica a porta TCP/IP, ou a extensão de
arquivo de soquete de domínio
Unix local, onde o
postgres deve escutar conexões de aplicações
cliente.
O padrão é o valor da variável de ambiente PGPORT
ou, se PGPORT não estiver definida, o padrão é o
valor estabelecido durante a construção (normalmente 5432).
Se for especificada uma porta diferente da porta padrão, todas
as aplicações cliente deverão especificar a mesma porta usando
opções de linha de comando, ou PGPORT.
-sMostra informações de tempo e outras estatísticas no final de cada comando. É útil para medições (benchmarking), ou para uso no ajuste do número de buffers.
-S memória_de_trabalho
Especifica a quantidade base de memória a ser usada por
classificações e tabelas de hash,
antes de recorrer a arquivos em disco temporários.
Veja a descrição do parâmetro de configuração
work_mem em
Memória.
-V--versionMostra a versão do postgres, e termina.
--nome=valor
Define o parâmetro de tempo de execução indicado;
uma forma mais curta da opção -c.
--describe-config
Esta opção descarrega as variáveis de configuração interna do
servidor, descrições e padrões no formato COPY
delimitado por tabulações.
Projetado principalmente para uso por ferramentas de administração.
-?--helpMostra a ajuda sobre os argumentos de linha de comando do postgres, e termina.
As opções descritas a seguir são usadas principalmente para fins de depuração e, em alguns casos, para auxiliar na recuperação de bancos de dados gravemente danificados. Não deve haver motivo para usá-las em uma configuração de banco de dados de produção. Estão listadas aqui apenas para uso por desenvolvedores de sistema do PostgreSQL. Além disso, estas opções podem ser alteradas ou removidas em uma versão futura sem prévio aviso.
-f { s | i | o | b | t | n | m | h }
Proíbe o uso de determinados métodos de varredura e junção:
s e i
desativam varreduras sequenciais e de índice, respectivamente;
o, b e t
desativam varreduras somente de índice, varreduras de índice de
bitmap e varreduras TID, respectivamente; enquanto
n, m, e h
desativam laço aninhado, mesclagem e junções de
hash, respectivamente.
Nem varreduras sequenciais, nem junções de laço aninhado, podem
ser desativadas inteiramente;
as opções -fs e -fn
simplesmente desencorajam o otimizador de usar estes tipos de
plano, se houver outra alternativa.
-O
Permite modificar a estrutura das tabelas do sistema.
É usada pelo initdb.
-PIgnora os índices do sistema ao ler as tabelas do sistema, mas ainda atualiza os índices ao modificar as tabelas. É útil ao recuperar índices do sistema danificados.
-t pa[rser] | pl[anner] | e[xecutor]
Mostra estatísticas de tempo para cada consulta relacionada
a cada um dos principais módulos do sistema.
Esta opção não pode ser usada junto com a opção -s.
-TEsta opção serve para depurar problemas que causam o término anormal de um processo servidor. A estratégia comum nesta situação é notificar todos os outros processos servidores de que eles devem ser encerrados, enviando-lhes sinais SIGQUIT. Com esta opção, será enviado SIGABRT em vez de SIGQUIT, resultando na geração de arquivos de despejo de memória (core dump).
-v protocoloEspecifica o número da versão do protocolo cliente/servidor (front-end/back-end) a ser usado para uma sessão específica. Esta opção é para uso interno apenas.
-W segundosUm atraso dessa quantidade de segundos ocorre quando um novo processo servidor é iniciado, após realizar o procedimento de autenticação. O objetivo é dar oportunidade de anexar um depurador ao processo servidor.
As opções a seguir se aplicam apenas ao modo mono-usuário (veja Modo mono-usuário abaixo).
--singleSeleciona o modo mono-usuário. Este deve ser o primeiro argumento na linha de comando.
banco_de_dadosEspecifica o nome do banco de dados a ser acessado. Este deve ser o último argumento na linha de comando. Se for omitido, o padrão é o nome do usuário.
-EEcoa todos os comandos na saída padrão antes de executar.
-jUsa ponto-e-vírgula seguido por duas novas-linhas, em vez de apenas uma nova-linha, como terminador de entrada de comando.
-r nome_do_arquivo
Envia toda a saída de registro (log)
do servidor para
nome_do_arquivo.
Esta opção só é respeitada quando fornecida como uma
opção de linha de comando.
PGCLIENTENCODINGCodificação de caracteres padrão usada pelos clientes. (Os clientes podem alterar este valor individualmente.) Este valor também pode ser definido no arquivo de configuração.
PGDATALocalização padrão do diretório de dados.
PGDATESTYLEValor padrão do parâmetro de tempo de execução DateStyle. (O uso dessa variável de ambiente está em obsolescência.)
PGPORTNúmero da porta padrão (de preferência definido no arquivo de configuração)
Uma mensagem de falha mencionando semget ou
shmget provavelmente indica que é necessário
configurar o núcleo (kernel), para
fornecer memória compartilhada e semáforos adequados.
Para obter mais informações veja Gerenciamento dos recursos do núcleo.
Pode ser adiada a reconfiguração do núcleo, diminuindo
shared_buffers para reduzir o consumo de
memória compartilhada pelo PostgreSQL,
e/ou reduzindo max_connections para reduzir
o consumo de semáforos.
Uma mensagem de falha sugerindo que outro servidor está em execução deve ser verificada com cuidado, por exemplo, usando o comando
$ps ax | grep postgres
ou
$ps -ef | grep postgres
dependendo do sistema. Se houver certeza de que nenhum servidor conflitante está em execução, pode ser removido o arquivo de bloqueio mencionado na mensagem e tentado novamente.
Uma mensagem de falha indicando a impossibilidade de ligação a uma
porta pode indicar que esta porta já está em uso por algum outro
processo não PostgreSQL.
Também pode acontecer este erro ao encerrar o
postgres, e reiniciá-lo imediatamente usando a
mesma porta; neste caso, basta aguardar alguns segundos até que o
sistema operacional feche a porta antes de tentar novamente.
Por fim, também pode ser visto este erro ao se especificar um número
de porta que o sistema operacional considera reservado.
Por exemplo, muitas versões do
Unix consideram os números
de porta abaixo de 1024 como “confiáveis”, permitindo
apenas que o superusuário do
Unix as acesse.
Pode ser usado o comando utilitário pg_ctl
para iniciar e desligar o servidor postgres
de forma segura e confortável.
Se possível, não deve ser usado
SIGKILL para derrubar o servidor
postgres principal.
Fazer isto impede que o postgres libere os recursos
do sistema operacional (por exemplo, memória compartilhada e semáforos)
mantidos por ele antes de terminar.
Isto pode causar problemas para iniciar uma nova execução do
postgres.
Para encerrar normalmente o servidor postgres
podem ser usados os sinais SIGTERM,
SIGINT ou SIGQUIT.
O primeiro aguarda que todos os clientes sejam encerrados antes de
sair, o segundo desconecta todos os clientes à força, e o terceiro s
encerra imediatamente sem o desligamento adequado, resultando
em uma execução de recuperação durante a reinicialização.
O sinal SIGHUP recarrega os arquivos de configuração do servidor. Também é possível enviar SIGHUP para um processo servidor individual, mas isto geralmente não faz sentido.
Para cancelar uma consulta em execução, deve ser enviado o sinal
SIGINT para o processo que executa este comando.
Para encerrar um processo servidor de forma limpa, deve ser enviado
o sinal SIGTERM para este processo.
Consulte também pg_cancel_backend e
pg_terminate_backend em
Funções de sinalização do servidor, para ver as chamadas
SQL equivalentes a estas duas ações.
O servidor postgres usa o sinal
SIGQUIT para informar ao processo servidor
subordinado para terminar sem efetuar a limpeza normal.
Este sinal não deve ser usado pelos usuários.
Também não se aconselha enviar um sinal SIGKILL
para um processo servidor — o processo postgres
principal irá interpretar isto como um travamento, e forçará todos os
processos irmãos a encerrar como parte de seu procedimento padrão
de recuperação de travamento.
As opções -- não funcionam no
FreeBSD e no
OpenBSD.
Deve ser usado -c em seu lugar.
Este é um bug nos sistemas
operacionais afetados;
uma versão futura do PostgreSQL fornecerá
uma solução alternativa, se isto não for corrigido.
Para iniciar um servidor no modo mono-usuário, deve ser usado um comando como
postgres --single -D /usr/local/pgsql/data outras_opções meu_banco_de_dados
Deve ser fornecido o caminho correto para o diretório do banco de
dados usando a opção -D, ou garantido que a
variável de ambiente PGDATA está definida.
Também deve ser especificado o nome do banco de dados onde se
deseja trabalhar.
Normalmente, o servidor no modo mono-usuário trata nova-linha como o terminador de entrada de comando; não há inteligência sobre ponto e vírgula, como há no psql. Para continuar o comando em várias linhas, deve-se digitar uma contrabarra antes de cada nova-linha, exceto a última. A contrabarra e nova-linha adjacente são removidas do comando de entrada. Note que isto acontece mesmo em um literal cadeia de caracteres ou comentário.
Mas se for usada a opção de linha de comando -j,
uma única nova-linha não encerra a entrada do comando; em vez disso,
a sequência ponto-e-vírgula-nova-linha-nova-linha o faz.
Ou seja, é digitado um ponto e vírgula seguido imediatamente
por uma linha completamente vazia.
Contrabarra-nova-linha não é tratada de modo especial neste modo.
Novamente, não há inteligência sobre esta sequência aparecendo
dentro de um literal cadeia de caracteres ou comentário.
Em qualquer um dos modos de entrada, se for digitado um ponto-e-vírgula que não esteja logo antes, ou faça parte de um terminador de entrada de comando, será considerado um separador de comando. Quando se digita um terminador de entrada de comando, as várias instruções inseridas são executadas como uma única transação.
Para sair da sessão, deve-se digitar EOF (Ctrl+D, geralmente). Se tiver sido digitado qualquer texto desde o último terminador de entrada de comando, o EOF será usado como terminador de entrada de comando, e será necessário outro EOF para sair.
Deve-se observar que o servidor no modo mono-usuário não fornece recursos sofisticados de edição de linha (sem histórico de comandos, por exemplo). O modo mono-usuário também não faz nenhum processamento em segundo plano, como pontos de verificação automáticos ou replicação.
Para iniciar o postgres em segundo plano usando
os valores padrão, deve-se digitar:
$nohup postgres >logfile 2>&1 </dev/null &
Para iniciar o postgres com uma porta específica,
por exemplo, 1234:
$postgres -p 1234
Para se conectar a este servidor usando o psql,
deve ser especificada esta porta com a opção -p:
$psql -p 1234
ou definida a variável de ambiente PGPORT:
$export PGPORT=1234$psql
Podem ser definidos parâmetros de tempo de execução específicos usando qualquer um desses estilos:
$postgres -c work_mem=1234$postgres --work-mem=1234
Qualquer uma dessas formas substitui qualquer configuração que possa
existir para work_mem no arquivo
postgresql.conf.
Note que sublinhados em nomes de parâmetros podem ser escritos
como sublinhado ou hífen na linha de comando.
Exceto para experimentos de curto prazo, provavelmente é uma prática
melhor editar a configuração no arquivo
postgresql.conf do que confiar em opção
de linha de comando para definir parâmetro.
Exemplo 175. Exemplo do tradutor
Ativação do servidor
Mostrar o status e parar o servidor usando o utilitário pg_ctl, e depois e ativar o servidor PostgreSQL 18 pelo postgres usando os dados fornecidos pelo status no Debian 12.
$sudo su - postgres$/usr/lib/postgresql/18/bin/pg_ctl status -D /var/lib/postgresql/18/main/pg_ctl: servidor está executando (PID: 3896) /usr/lib/postgresql/18/bin/postgres \ "-D" "/var/lib/postgresql/18/main" \ "-c" "config_file=/etc/postgresql/18/main/postgresql.conf"$/usr/lib/postgresql/18/bin/pg_ctl stop -D /var/lib/postgresql/18/main/esperando o servidor desligar....feito servidor está parado$truncate -s 0 nohup.out-- limpar o arquivo de saída$nohup /usr/lib/postgresql/18/bin/postgres \ "-D" "/var/lib/postgresql/18/main" \ "-c" "config_file=/etc/postgresql/18/main/postgresql.conf" &[1] 4045$nohup: ignorando entrada e anexando saída a 'nohup.out'-- Tecle Enter ou Ctrl+M$cat nohup.out-- mostrar o arquivo de saída 2026-06-02 06:39:44.940 -03 [4045] LOG: iniciando PostgreSQL 18.1 ... 2026-06-02 06:39:44.941 -03 [4045] LOG: escutando no endereço IPv6 "::1", porta 5432 2026-06-02 06:39:44.941 -03 [4045] LOG: escutando no endereço IPv4 "127.0.0.1", porta 5432 2026-06-02 06:39:44.942 -03 [4045] LOG: escutando no soquete Unix "/var/run/postgresql/.s.PGSQL.5432" 2026-06-02 06:39:44.962 -03 [4051] LOG: sistema de banco de dados foi desligado em 2026-06-02 06:32:27 -03 2026-06-02 06:39:44.970 -03 [4045] LOG: sistema de banco de dados está pronto para aceitar conexões$/usr/lib/postgresql/18/bin/pg_ctl status -D /var/lib/postgresql/18/main/pg_ctl: servidor está executando (PID: 4045) /usr/lib/postgresql/18/bin/postgres \ "-D" "/var/lib/postgresql/18/main" \ "-c" "config_file=/etc/postgresql/18/main/postgresql.conf"