pg_receivewal — transmite registros de escrita antecipada de um servidor PostgreSQL
pg_receivewal [opção...]
Figura 8. Replicação física no PostgreSQL
O utilitário pg_receivewal é usado para transmitir registros de escrita antecipada (WAL) do agrupamento de bancos de dados (cluster) de uma instância do PostgreSQL ativa. O registro de escrita antecipada é transmitido usando o protocolo de replicação por fluxo (streaming) e escrito em um diretório local. Este diretório pode ser usado como local de arquivamento para realizar uma restauração usando a recuperação para um ponto no tempo (veja Continuous Archiving and Point-in-Time Recovery (PITR)).
O utilitário pg_receivewal transmite os registros de escrita antecipada em tempo real conforme estes são gerados no servidor sem esperar que os segmentos sejam concluídos, como archive_command e archive_library fazem Por este motivo, não é necessário definir archive_timeout ao usar o utilitário pg_receivewal.
Diferentemente do receptor de WAL de um servidor
PostgreSQL em-espera, o utilitário
pg_receivewal, por padrão, descarrega os
dados do WAL no disco somente quando o arquivo do
WAL é fechado.
Deve ser especificada a opção --synchronous para
descarregar os dados do WAL em tempo real.
Como o utilitário pg_receivewal não aplica
o WAL, não se deve permitir que este se torne um
servidor em-espera síncrono quando synchronous_commit
estiver definido como remote_apply.
Caso isto aconteça, vai parecer ser um servidor em-espera que nunca
consegue se atualizar, causando o bloqueio das efetivações de transação.
Para evitar que isto aconteça, deve-se definir um valor apropriado
para synchronous_standby_names, ou especificar
um valor para o parâmetro application_name para
pg_receivewal que não corresponda,
ou alterar o valor de synchronous_commit para
algo diferente de remote_apply.
O registro de escrita antecipada é transmitido por meio de uma
conexão do PostgreSQL regular,
e usa o protocolo de replicação.
A conexão deve ser feita por um usuário que tenha permissões
REPLICATION (veja Role Attributes),
ou um superusuário, e o arquivo pg_hba.conf deve
permitir conexão de replicação.
O servidor também deve ser configurado com
max_wal_senders definido alto o suficiente
para deixar pelo menos uma sessão disponível para a transmissão.
O ponto de início do fluxo de registro de escrita antecipada é calculado quando o utilitário pg_receivewal inicia:
Primeiro, é varrido o diretório onde os arquivos de segmento do WAL são escritos, e encontrado o arquivo de segmento concluído mais recentemente, para usar como ponto de partida para o próximo arquivo de segmento do WAL.
Se não for possível calcular o ponto de partida com o método
anterior, e se for usado encaixe de replicação,
será emitido um comando READ_REPLICATION_SLOT
extra para recuperar o restart_lsn do encaixe
para usar como ponto de partida.
Esta opção está disponível apenas ao transmitir
registro de escrita antecipada do
PostgreSQL versão 15 ou superior.
Se não for possível calcular um ponto de partida usando o método
anterior, será usado o local de descarga do WAL
mais recente conforme relatado pelo servidor segundo o comando
IDENTIFY_SYSTEM.
Se a conexão for perdida, ou se não puder ser estabelecida
inicialmente devido a erro não fatal, então o utilitário
pg_receivewal tentará novamente a conexão
indefinidamente, e restabelecerá o fluxo o mais rápido possível.
Para evitar este comportamento, deve ser usado o parâmetro
-n.
Na ausência de erros fatais, o utilitário pg_receivewal permanecerá em execução até ser encerrado pelo sinal SIGINT (Control+C) ou SIGTERM.
-D diretório--directory=diretórioDiretório para escrever a saída.
Parâmetro obrigatório.
-E lsn--endpos=lsn
Interrompe automaticamente a replicação, e termina com o status
de saída normal 0, quando o recebimento
atingir o LSN especificado.
Caso exista um registro com LSN exatamente
igual a lsn, o registro será processado.
--if-not-exists
Não relata erro quando é especificado --create-slot,
e já existir o encaixe (slot)
com o nome especificado.
-n--no-loopNão insista em erros de conexão. Em vez disso, termine imediatamente com um erro.
--no-sync
Esta opção faz com que o utilitário
pg_receivewal não force que os dados do
WAL sejam descarregados para o disco.
Assim fica mais rápido, mas significa que uma falha subsequente
do sistema operacional pode deixar os segmentos do
WAL corrompidos.
Geralmente, esta opção é útil para testes, mas não deve ser
usada ao arquivar o WAL em uma instalação
de produção.
Esta opção é incompatível com --synchronous.
-s intervalo--status-interval=intervaloEspecifica o número de segundos entre os pacotes de status enviados de volta ao servidor. Permite um monitoramento mais fácil do progresso do servidor. O valor zero desativa completamente as atualizações periódicas de status, embora uma atualização ainda seja enviada quando solicitada pelo servidor, para evitar desconexão por timeout. O valor padrão é de 10 segundos.
-S nome_do_encaixe--slot=nome_do_encaixeRequer que o utilitário pg_receivewal use um encaixe de replicação existente (veja Seção 26.2.6). Quando esta opção é usada, o utilitário pg_receivewal irá relatar uma posição de liberação ao servidor, indicando quando cada segmento foi sincronizado com o disco, para que o servidor possa remover este segmento se não for mais necessário.
Quando o cliente de replicação do utilitário
pg_receivewal é configurado no
servidor como em-espera (standby)
síncrono, o uso de um encaixe de replicação reportará a posição
de liberação ao servidor, mas somente quando o arquivo
do WAL for fechado.
Portanto, esta configuração fará com que as transações no
servidor primário esperem muito tempo, e efetivamente não
funcionem satisfatoriamente.
A opção --synchronous (veja abaixo) deve
ser especificada para que isto funcione corretamente.
--synchronous
Descarrega os dados do WAL para o disco
imediatamente após serem recebidos.
Também envia um pacote de status de volta ao servidor
imediatamente após a liberação, independentemente do
--status-interval.
Esta opção deve ser especificada se o cliente de replicação de pg_receivewal estiver configurado no servidor como em-espera síncrono, para garantir que seja enviado ao servidor um retorno oportuno.
-v--verboseAtiva o modo verboso.
-Z nível-Z método[:detalhe]--compress=nível--compress=método[:detalhe]Ativa a compressão dos registros de escrita antecipada.
O método de compressão pode ser definido como
gzip, lz4
(se o PostgreSQL
foi compilado com --with-lz4) ou
none para nenhuma compressão.
Opcionalmente, pode ser especificada uma cadeia de caracteres
com detalhes de compressão.
Se a cadeia de caracteres de detalhes for um número inteiro,
ela especifica o nível de compressão.
Caso contrário, deve ser uma lista de itens separados por
vírgulas, cada um no formato
palavra-chave ou
palavra-chave=valor.
No momento, a única palavra-chave com suporte é
level.
Se não for especificado nenhum nível de compressão,
será usado o nível de compressão padrão.
Se for especificado apenas o nível sem mencionar o algoritmo,
então será usada a compressão gzip se o nível
for maior que 0, e não será usada nenhuma compressão se o nível
for igual a 0.
Será adicionado o sufixo .gz
automaticamente a todos os nomes de arquivo ao usar o
gzip, e adicionado o sufixo
.lz4 ao usar o lz4.
As opções de linha de comando a seguir controlam os parâmetros de conexão com o banco de dados.
-d cadeia_de_caracteres_de_conexão--dbname=cadeia_de_caracteres_de_conexãoEspecifica os parâmetros usados para conectar ao servidor como uma cadeia de caracteres de conexão; os parâmetros da cadeia de caracteres de conexão têm precedência sobre quaisquer opções de linha de comando conflitantes.
Esta opção se chama --dbname para manter
a consistência com outras aplicações cliente,
mas como o utilitário pg_receivewal
não se conecta a nenhum banco de dados específico no agrupamento,
qualquer nome de banco de dados incluído na cadeia de caracteres
de conexão será ignorado pelo servidor.
Entretanto, um nome de banco de dados fornecido dessa forma
substitui o nome de banco de dados padrão
(replication) para fins de consulta da senha
da conexão de replicação em ~/.pgpass.
Da mesma forma, os intermediários
(middlewares) ou procuradores
(proxies) usados na conexão com
o PostgreSQL podem utilizar o nome
para fins como roteamento de conexão.
-h hospedeiro--host=hospedeiro
Especifica o nome do hospedeiro da máquina na qual o servidor
está sendo executado.
Se começar com uma barra, será usado como o diretório para o
soquete de domínio Unix.
O padrão é obtido da variável de ambiente PGHOST,
se definida, caso contrário, é tentada uma conexão de soquete de
domínio Unix.
-p porta--port=porta
Especifica a porta TCP, ou extensão de
arquivo de soquete de domínio
Unix local,
na qual o servidor está aguardando conexões.
O padrão é usar a variável de ambiente PGPORT,
se estiver definida, ou o padrão compilado.
-U nome_do_usuário--username=nome_do_usuárioNome de usuário para se conectar como.
-w--no-password
Nunca emite uma solicitação de senha.
Se o servidor exigir autenticação por senha, e uma senha não
estiver disponível por outros meios, como o arquivo
.pgpass, a tentativa de conexão irá falhar.
Esta opção pode ser útil em tarefas em lote e scripts nos quais
nenhum usuário está presente para inserir uma senha.
-W--passwordForça o pg_receivewal solicitar a senha antes de conectar ao banco de dados.
Esta opção nunca é essencial, porque o
pg_receivewal solicita automaticamente
a senha se o servidor exigir autenticação por senha.
No entanto, o pg_receivewal irá
desperdiçar uma tentativa de conexão ao descobrir que o servidor
pede uma senha.
Em alguns casos vale a pena digitar -W para
evitar a tentativa extra de conexão.
O utilitário pg_receivewal pode executar uma dessas duas ações para controlar os encaixes de replicação física:
--create-slot
Cria um novo encaixe de replicação física com o nome
especificado em --slot, e termina.
--drop-slot
Remove o encaixe de replicação com o nome especificado em
--slot, e termina.
Também estão disponíveis outras opções:
-V--versionMostra a versão pg_receivewal, e termina.
-?--helpMostra a ajuda sobre os argumentos da linha de comando pg_receivewal, e termina.
O utilitário pg_receivewal irá encerrar com o código de saída 0 quando terminado pelo sinal SIGINT ou SIGTERM. (Esta é a forma normal de terminar. Portanto, não é um erro.) Em caso de erros fatais ou outros sinais, o código de saída será diferente de zero.
Este utilitário, como a maioria dos outros utilitários do PostgreSQL, usa as variáveis de ambiente com suporte pela libpq (veja Variáveis de ambiente).
A variável de ambiente PG_COLOR especifica se devem
ser usadas cores nas mensagens de diagnóstico.
Os valores possíveis são always,
auto e never.
Ao usar o utilitário pg_receivewal em vez de archive_command ou archive_library como o principal método de cópia de segurança do WAL, é altamente recomendável usar encaixes de replicação. Caso contrário, o servidor ficará livre para reciclar ou remover os arquivos de registro de escrita antecipada antes que eles sejam copiados, porque não possui nenhuma informação, seja do archive_command, ou dos encaixes de replicação, sobre até que ponto o fluxo de WAL foi arquivado. Note, no entanto, que o encaixe de replicação ocupará todo o espaço livre no disco do servidor, se o receptor não conseguir acompanhar a transmissão dos dados do WAL
O utilitário pg_receivewal irá preservar as permissões de grupo nos arquivos de WAL recebidos, se as permissões de grupo estiverem ativas na instância de origem.
Para transmitir o registro de escrita antecipada do servidor em
mydbserver e armazená-lo no diretório local
/usr/local/pgsql/archive:
$pg_receivewal -h mydbserver -D /usr/local/pgsql/archive