pg_recvlogical

pg_recvlogical
Anterior	Acima	Aplicações cliente do PostgreSQL	Principal	Próxima

Descrição

Figura 9. Replicação lógica no PostgreSQL

O utilitário pg_recvlogical controla os encaixes (slots) de replicação para decodificação lógica, e transmite por fluxo os dados desses encaixes de replicação.

Cria uma conexão no modo de replicação, portanto, está sujeito às mesmas restrições que pg_receivewal, mais os da replicação lógica (veja Logical Decoding).

O utilitário pg_recvlogical não tem equivalente para os modos peek e get da interface SQL de decodificação lógica. Ele envia as confirmações de replicação dos dados lentamente quando as recebe, e no término sem erro. Para examinar os dados pendentes em um encaixe sem os consumir, deve ser usada a função pg_logical_slot_peek_changes.

Na ausência de erros fatais, o utilitário pg_recvlogical permanecerá em execução até ser encerrado pelo sinal SIGINT (Control+C) ou SIGTERM.

Quando utilitário pg_recvlogical recebe um sinal SIGHUP, ele fecha o arquivo de saída corrente e abre um novo usando o nome de arquivo especificado pela opção --file. Isto permite rotacionar o arquivo de saída, primeiro renomeando o arquivo corrente, e depois enviando um sinal SIGHUP para o pg_recvlogical.

Opções

Deve ser especificada pelo menos uma das seguintes opções para selecionar uma ação:

--create-slot

Cria um novo encaixe de replicação lógica com o nome especificado por --slot, usando o plug-in de saída especificado por --plugin, para o banco de dados especificado por --dbname.

As opções --slot e --dbname são requeridas para esta ação.

As opções --enable-two-phase e --enable-failover podem ser especificadas junto com a opção --create-slot.

--drop-slot

Remove o encaixe de replicação com o nome especificado por --slot, e termina.

A opção --slot é requerida para esta ação.

--start

Começa a transmitir as modificações do encaixe de replicação lógica especificado por --slot, continuando até terminar por um sinal. Se o fluxo de modificação do lado servidor terminar por um desligamento ou desconexão do servidor, tenta novamente em um ciclo, a menos que seja especificado --no-loop.

As opções --slot, --dbname e --file são requeridas para esta ação.

O formato do fluxo é determinado pelo plug-in de saída especificado quando o encaixe foi criado.

A conexão deve ser com o mesmo banco de dados usado para criar o encaixe.

As opções --create-slot e --start podem ser especificadas juntas. A opção --drop-slot não pode ser combinada com outra ação.

As seguintes opções de linha de comando controlam o local e o formato da saída, e outros comportamentos de replicação:

-E lsn --endpos=lsn

No modo --start, termina automaticamente a replicação, saindo com o código de saída normal 0 quando o recebimento atinge o LSN especificado. Se for especificado quando não estiver no modo --start, será relatado um erro.

Se houver um registro com o LSN exatamente igual a lsn, o registro será processado.

A opção --endpos não reconhece limites de transação, podendo truncar a saída no meio de uma transação. Qualquer saída parcial de transação não será consumida, e será reproduzida novamente na próxima leitura do encaixe. As mensagens individuais nunca são truncadas.

--enable-failover

Ativa a sincronização de encaixes com servidores em espera. Esta opção só pode ser usada com --create-slot.

-f nome_do_arquivo --file=nome_do_arquivo

Escreve os dados de transação recebidos e decodificados neste arquivo. Deve ser usado o caractere - para especificar stdout.

Este parâmetro é requerido para --start.

-F intervalo_em_segundos --fsync-interval=intervalo_em_segundos

Especifica com que frequência pg_recvlogical deve executar chamadas fsync() para garantir que o arquivo de saída seja descarregado com segurança para o disco.

Ocasionalmente, o servidor pede que o cliente execute uma descarga e relate a posição da descarga ao servidor. Esta configuração se soma a este pedido, para realizar descargas com mais frequência.

Especificar um intervalo igual a 0 desativa completamente a execução de chamadas a fsync(), enquanto ainda relata o progresso para o servidor. Neste caso, podem ser perdidos dados em caso de falha.

-I lsn --startpos=lsn

No modo --start, inicia a replicação a partir do LSN fornecido. Para obter detalhes sobre o efeito dessa opção, veja a documentação em Logical Decoding e Seção 54.4. É ignorado em outros modos.

--if-not-exists

Não lança um erro quando é especificado --create-slot, e já existir um encaixe com o nome especificado.

-n --no-loop

Quando a conexão com o servidor é perdida, não tenta novamente em ciclos, apenas termina.

-o nome[=valor] --option=nome[=valor]

Passa a opção nome para o plug-in de saída, com o valor, se especificado. Quais opções existem e seus efeitos dependem do plug-in de saída usado.

-P plugin --plugin=plugin

Ao criar um encaixe, usa a saída do plugin de decodificação lógica especificado. Veja Logical Decoding. Esta opção não terá efeito se o encaixe já existir.

-s intervalo_em_segundos --status-interval=intervalo_em_segundos

Esta opção tem o mesmo efeito que a opção de mesmo nome em pg_receivewal. Veja a descrição lá.

-S nome_do_encaixe --slot=nome_do_encaixe

No modo --start, usa o encaixe de replicação lógica existente chamado nome_do_encaixe. No modo --create-slot, cria o encaixe com este nome. No modo --drop-slot, exclui o encaixe com este nome.

Este parâmetro é requerido para todas as ações.

-t --enable-two-phase --two-phase (obsoleto)

Ativa a decodificação de transações preparadas. Esta opção só pode ser especificada com --create-slot.

-v --verbose

Ativa o modo verboso.

As opções de linha de comando a seguir controlam os parâmetros de conexão com o banco de dados.

-d nome_do_banco_de_dados --dbname=nome_do_banco_de_dados

O banco de dados ao qual se conectar. Veja a descrição das ações para saber o que isto significa em detalhes. O nome_do_banco_de_dados pode ser uma cadeia de caracteres de conexão. Neste caso, os parâmetros da cadeia de caracteres de conexão prevalecem sobre quaisquer opções de linha de comando conflitantes.

Este parâmetro é requerido para --create-slot e --start.

-h hospedeiro_ou_ip --host=hospedeiro_ou_ip

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 a extensão do arquivo de soquete de domínio Unix local, na qual o servidor está ouvindo as conexões. O padrão é usar a variável de ambiente PGPORT, se estiver definida, ou o padrão compilado.

-U usuário --username=usuário

Nome de usuário para se conectar como. O padrão é o nome de usuário corrente do sistema operacional.

-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 --password

Força o pg_recvlogical solicitar a senha antes de conectar ao banco de dados.

Esta opção nunca é essencial, porque o pg_recvlogical irá solicitar automaticamente a senha se o servidor exigir autenticação por senha. Entretanto, o pg_recvlogical 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.

Estão disponíveis as seguintes opções adicionais:

-V --version: Mostra a versão do pg_recvlogical, e termina.
-? --help: Mostra a ajuda sobre os argumentos da linha de comando do utilitário pg_recvlogical, e termina.

Código de saída

O utilitário pg_recvlogical 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.

Variáveis de ambiente

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.

Notas

O utilitário pg_recvlogical irá preservar as permissões de grupo nos arquivos WAL recebidos, se as permissões de grupo estiverem ativas na instância de origem.

Exemplos

Veja exemplos em Logical Decoding Examples.

Exemplo 157. Exemplo do tradutor

Uso do pg_recvlogical com o plugin test_decoding

Neste exemplo o utilitário pg_recvlogical é usado para criar o encaixe de replicação lógica chamado cristina, para o banco de dados cristina, usando o plugin test_decoding e escrevendo os dados decodificados na saída padrão stdout. O resultado mostrado corresonde a uma linha inserida na tabela salario_emp pela usuária cristina após a tabela ser truncada.

$ psql
postgres=# ALTER SYSTEM SET wal_level = 'logical';
ALTER SYSTEM
postgres=# ALTER SYSTEM SET max_replication_slots = 10;
ALTER SYSTEM
postgres=# exit
$ sudo systemctl restart postgresql
$ pg_recvlogical --create-slot \
--slot=cristina \
--dbname=cristina \
--plugin=test_decoding \
--file=-
$ pg_recvlogical --start \
--slot=cristina \
--dbname=cristina \
--file=-

BEGIN 1557
table public.salario_emp: TRUNCATE: (no-flags)
COMMIT 1557
BEGIN 1558
table public.salario_emp: ↵
    INSERT: nome_dep[text]:'desenvolvimento' ↵
            num_emp[bigint]:13 ↵
            salario[integer]:6000 ↵
            data_adm[date]:'2026-04-14'
COMMIT 1558
^C

$ pg_recvlogical --drop-slot --slot=cristina

Exemplo 158. Exemplo do tradutor

Uso do pg_recvlogical com o plugin wal2json

Mesmo exemplo anterior usando o plugin wal2json.

$ sudo apt-get install postgresql-18-wal2json
$ pg_recvlogical --create-slot \
--slot=cristina \
--dbname=cristina \
--plugin=wal2json \
--file=-
$ pg_recvlogical --start \
--slot=cristina \
--dbname=cristina \
--file=-

{"change":[]}
{"change":[{"kind":"insert","schema":"public","table":"salario_emp", ↵
"columnnames":["nome_dep","num_emp","salario","data_adm"], ↵
"columntypes":["text","bigint","integer","date"], ↵
"columnvalues":["desenvolvimento",13,6000,"2026-04-14"]}]}
^C

$ pg_recvlogical --drop-slot --slot=cristina

Veja também

pg_receivewal, CREATE PUBLICATION, DROP PUBLICATION