pg_createsubscriber — converte uma réplica física em uma nova réplica lógica
pg_createsubscriber [opção...] { -d | --database } banco { -D | --pgdata } diretório { -P | --publisher-server } conexão
O utilitário pg_createsubscriber cria uma nova réplica lógica a partir de um servidor físico em-espera. Todas as tabelas no banco de dados especificado são incluídas na configuração de replicação lógica. Para cada banco de dados, são criados um par de objetos de publicação e subscrição. Deve ser executado no servidor de destino.
Após uma execução bem-sucedida, o estado do servidor de destino é análogo a uma nova configuração de replicação lógica. A principal diferença entre a configuração de replicação lógica e o utilitário pg_createsubscriber é como a sincronização de dados é feita. O utilitário pg_createsubscriber não copia os dados iniciais da tabela. É executado apenas a fase de sincronização, que garante que cada tabela seja colocada em um estado sincronizado.
O utilitário pg_createsubscriber
é direcionado a grandes sistemas de banco de dados porque,
na configuração de replicação lógica, a maior parte do tempo
é gasto na cópia inicial dos dados.
Além disso, um efeito colateral desse longo tempo gasto na
sincronização de dados é geralmente uma enorme quantidade de
alterações a serem aplicadas (que foram produzidas durante a cópia
inicial dos dados), o que aumenta ainda mais o tempo em que a
réplica lógica estará disponível.
Para bancos de dados menores, recomenda-se configurar a replicação
lógica com sincronização inicial de dados.
Para obter mais informações, veja a opção
copy_data
do comando CREATE SUBSCRIPTION.
O utilitário pg_createsubscriber aceita os seguintes argumentos de linha de comando:
-a--all
Cria uma subscrição por banco de dados no servidor de destino.
As exceções são os bancos de dados de modelo e bancos de dados
que não permitem conexões.
Para descobrir a lista de todos os bancos de dados, deve-se
conectar ao servidor de origem usando o nome do banco de dados
especificado na cadeia de caracteres de conexão
--publisher-server ou, se não for especificado,
será usado o banco de dados postgres ou,
se este não existir, será usado o banco de dados
template1.
Ao especificar esta opção, são utilizados nomes gerados
automaticamente para subscrições, publicações e espaços de
replicação.
Esta opção não pode ser usada em conjunto com
--database, --publication,
--replication-slot ou
--subscription.
-d banco--database=banco
O nome do banco de dados no qual criar uma subscrição.
É possível selecionar vários bancos de dados escrevendo várias
opções -d.
Esta opção não pode ser usada em conjunto com a opção
-a.
Se não for fornecida a opção -d, o nome do
banco de dados será obtido da opção -P.
Se o nome do banco de dados não for especificado na opção
-d, ou na opção -P,
e não for especificada a opção -a,
será relatado um erro.
-D diretório--pgdata=diretórioO diretório de destino que contém o diretório do agrupamento de bancos de dados de uma réplica física.
-n--dry-runFaz tudo, exceto modificar o diretório de destino.
-p porta--subscriber-port=portaO número da porta na qual o servidor de destino está aceitando conexões. Por padrão, o servidor de destino é executado na porta 50432 para evitar conexões de clientes não intencionais.
-P conexão--publisher-server=conexãoA cadeia de caracteres de conexão com o publicador. Para obter mais informações, veja Cadeias de caracteres de conexão.
-s diretório--socketdir=diretório
O diretório a ser usado para os
soquetes do postmaster no servidor
de destino.
O padrão é o diretório corrente.
-t segundos--recovery-timeout=segundosNúmero máximo de segundos para se aguardar que a recuperação termine. Definir como 0 desativa. O valor padrão é 0.
-T--enable-two-phase
Ativa a efetivação em
duas_fases para a subscrição.
Quando são especificados vários bancos de dados, esta opção
aplica-se uniformemente a todas as subscrições criadas nesses
bancos de dados.
O valor padrão é false.
-U nome_de_usuário--subscriber-username=nome_de_usuárioO nome de usuário para conexão no servidor de destino. Por padrão, usa o nome corrente do usuário do sistema operacional.
-v--verboseAtiva o modo verboso. Faz com que o utilitário pg_createsubscriber exiba mensagens de progresso e informações detalhadas sobre cada etapa na saída de erro padrão. Repetir esta opção faz com que surjam mensagens adicionais de nível de depuração na saída erro padrão.
--clean=tipo_do_objetoRemove todos os objetos do tipo especificado dos bancos de dados especificados no servidor de destino.
publications:
As publicações FOR ALL TABLES estabelecidas
para este subscritor são sempre excluídas; especificar este
tipo de objeto fará com que todas as outras publicações
replicadas do servidor de origem também sejam excluídas.
Os objetos selecionados para serem excluídos são registrados
individualmente, inclusive durante o --dry-run.
Não há oportunidade para afetar ou parar a exclusão dos objetos
selecionados, portanto deve-se considerar fazer uma cópia de
segurança deles usando o utilitário
pg_dump.
--config-file=nome_do_arquivo
Usa o arquivo de configuração do servidor principal
especificado para o diretório de dados de destino.
O utilitário pg_createsubscriber
usa internamente o utilitário pg_ctl
para iniciar e parar o servidor de destino.
Esta opção permite especificar o arquivo de configuração
postgresql.conf real, caso ele esteja
armazenado fora do diretório de dados.
--publication=nome
O nome da publicação para configurar a replicação lógica.
É possível especificar várias publicações escrevendo várias
opções --publication.
O número de nomes de publicações deve corresponder ao número de
bancos de dados especificados; caso contrário, será relatado um erro.
A ordem dos nomes das várias opções de publicação deve corresponder
à ordem das opções de banco de dados.
Caso esta opção não seja especificada, será atribuído um nome
gerado automaticamente ao nome da publicação.
Esta opção não pode ser usada em conjunto com a opção
--all.
--replication-slot=nome
O nome do encaixe de replicação para configurar a replicação lógica.
Podem ser especificados vários encaixes de replicação escrevendo
várias opções --replication-slot.
O número de nomes de encaixes de replicação deve corresponder ao
número de bancos de dados especificados; caso contrário, será
relatado um erro.
A ordem das múltiplas opções de nome de encaixe de replicação
deve corresponder à ordem das opções de banco de dados.
Caso esta opção não seja especificada, o nome da subscrição
será atribuído ao nome do encaixe de replicação.
Esta opção não pode ser usada em conjunto com a opção
--all.
--subscription=nome
O nome da subscrição para configurar a replicação lógica.
Podem ser especificadas várias subscrições escrevendo várias
opções --subscription.
O número de nomes de subscrição deve corresponder ao número de
bancos de dados especificados; caso contrário, será relatado um erro.
A ordem das múltiplas opções de nome de subscrição
deve corresponder à ordem das opções de banco de dados.
Caso esta opção não seja especificada, será atribuído um nome
gerado automaticamente ao nome da subscrição.
Esta opção não pode ser usada em conjunto com a opção
--all.
-V--versionMostra a versão do utilitário pg_createsubscriber, e termina.
-?--helpMostra a ajuda sobre os argumentos da linha de comando do utilitário pg_createsubscriber, e termina.
Existem alguns pré-requisitos para que o utilitário
pg_createsubscriber converta o servidor
de destino em uma réplica lógica.
Caso estes requisitos não sejam atendidos, será relatado um erro.
Os servidores de origem e destino devem ter a mesma versão principal
que o utilitário pg_createsubscriber.
O diretório de dados de destino especificado deve ter o mesmo
identificador de sistema que o diretório de dados de origem.
O usuário do banco de dados especificado para o diretório de dados
de destino deve ter privilégios para criar
subscrições e usar
a função pg_replication_origin_advance().
O servidor de destino deve ser usado como um servidor em-espera físico.
O servidor de destino deve ter
max_active_replication_origins e
max_logical_replication_workers configurado
para um valor maior ou igual ao número de bancos de dados especificados.
O servidor de destino deve ter
max_worker_processes configurado para um valor
maior que o número de bancos de dados especificados.
O servidor de destino deve aceitar conexões locais.
Se estiver planejado usar a opção --enable-two-phase
então também será necessário configurar
max_prepared_transactions de forma apropriada.
O servidor de origem deve aceitar conexões do servidor de destino.
O servidor de origem não deve estar em modo de recuperação.
O servidor de origem deve ter wal_level
configurado como logical.
O servidor de origem deve ter max_replication_slots
configurado para um valor maior ou igual ao número de bancos de dados
especificados mais os encaixes de replicação existentes.
O servidor de origem deve ter max_wal_senders
configurado para um valor maior ou igual ao número de bancos de
dados especificados e processos de envio de WAL
existentes.
Se o utilitário pg_createsubscriber falhar após o servidor de destino ter sido promovido, é provável que o diretório de dados não esteja em um estado que possa ser recuperado. Neste caso, recomenda-se a criação de um novo servidor em-espera.
O utilitário pg_createsubscriber geralmente inicia o servidor de destino com configurações de conexão diferentes durante a transformação. Portanto, as conexões com o servidor de destino devem falhar.
Como os comandos de DDL não são replicados pela replicação lógica, deve-se evitar executar comandos de DDL que alterem o esquema do banco de dados durante a execução do utilitário pg_createsubscriber. Se o servidor de destino já tiver sido convertido em réplica lógica, os comandos de DDL podem não ser replicados, o que pode causar erro.
Se o utilitário pg_createsubscriber falhar enquanto estiver processando, os objetos (publicações, encaixes de replicação) criados no servidor de origem serão removidos. A remoção pode falhar se o servidor de destino não conseguir se conectar ao servidor de origem. Neste caso, uma mensagem de aviso irá informar sobre os objetos deixados para trás. Se o servidor de destino estiver em execução, ele será parado.
Se a replicação estiver usando primary_slot_name, este será removido do servidor de origem após a configuração da replicação lógica.
Se o servidor de destino for uma réplica síncrona, as confirmações de transação no servidor primário podem aguardar pela replicação durante a execução do utilitário pg_createsubscriber.
A menos que a opção --enable-two-phase esteja
especificada, o utilitário
pg_createsubscriber configura a replicação
lógica com a efetivação em duas-fases como desativada.
Isto significa que quaisquer transações preparadas serão replicadas
no momento da execução do comando COMMIT PREPARED,
sem preparação prévia.
Após a configuração estar concluída, pode-se cancelar e recriar
manualmente as subscrições com a opção
two_phase ativa.
O utilitário pg_createsubscriber altera o identificador do sistema usando o utilitário pg_resetwal. Isto evitaria situações em que o servidor de destino pudesse usar arquivos de WAL do servidor de origem. Se o servidor de destino tiver um servidor em-espera, a replicação será interrompida e um novo servidor em-espera deverá ser criado.
Podem ocorrer falhas de replicação se faltarem os arquivos
de WAL necessários.
Para evitar isto, o servidor de origem deve configurar
max_slot_wal_keep_size como -1
para garantir que os arquivos de WAL necessários
não sejam removidos prematuramente.
A ideia básica é ter um ponto de partida de replicação no servidor de origem e configurar uma replicação lógica para começar a partir desse ponto:
Inicie o servidor de destino com as opções de linha de comando especificadas. Se o servidor de destino já estiver em execução, o utilitário pg_createsubscriber será encerrado com erro.
Verifique se o servidor de destino pode ser convertido. Também são realizadas algumas verificações no servidor de origem. Se algum dos pré-requisitos não for atendido, o utilitário pg_createsubscriber será encerrado com erro.
Crie um encaixe de publicação e replicação para cada banco de
dados especificado no servidor de origem.
Cada publicação é criada usando
FOR ALL TABLES.
Se não for especificada a opção --publication,
a publicação terá o seguinte padrão de nomenclatura:
“pg_createsubscriber_%u_%x”
(parameter: database oid,
random int).
Se não for especificada a opção --replication-slot,
o encaixe de replicação terá o seguinte padrão de nome:
“pg_createsubscriber_%u_%x”
(parameters: database oid,
random int).
Estes espaços de replicação serão usados pelas subscrições em uma
etapa futura.
O último LSN de encaixe de replicação é usado como ponto de parada
parâmetro recovery_target_lsn e pelas
subscrições como ponto de partida da replicação.
Isto garante que nenhuma transação será perdida.
Escreva os parâmetros de recuperação no diretório de dados de
destino e reinicie o servidor de destino.
Isto especifica o LSN (recovery_target_lsn)
do local do registro de escrita antecipada até o qual a
recuperação irá prosseguir.
Também especifica promote como a ação que o
servidor deverá tomar assim que a meta de recuperação for atingida.
São adicionados parâmetros de recuperação adicionais
para evitar comportamentos inesperados durante o processo de
recuperação, como o término da recuperação assim que um estado
consistente for alcançado (o WAL deve ser
aplicado até o local de início da replicação.) e múltiplos
destinos de recuperação que podem causar uma falha.
Esta etapa termina quando o servidor sai do modo em-espera e
está aceitando transações de leitura e escrita.
Se estiver definida a opção --recovery-timeout,
o utilitário pg_createsubscriber
irá encerrar se a recuperação não terminar dentro do número de
segundos especificado.
Crie uma subscrição para cada banco de dados especificado no
servidor de destino.
Se a opção --subscription não estiver
especificada, a subscrição terá o seguinte padrão de nome:
“pg_createsubscriber_%u_%x”
(parameters: database oid,
random int).
Isto não copia dados existentes do servidor de origem.
Isto não cria um encaixe de replicação.
Em vez disso, utiliza o encaixe de replicação que foi criado
numa etapa anterior.
A subscrição foi criada, mas ainda não está ativa.
O motivo é que o progresso da replicação deve ser definido para
o ponto inicial da replicação antes de iniciá-la.
Exclua as publicações no servidor de destino que foram replicadas, porque foram criadas antes do local de início da replicação. Isto não tem utilidade para o subscritor.
Defina o progresso da replicação para o ponto inicial da
replicação para cada subscrição.
Quando o servidor de destino inicia o processo de recuperação,
ele se atualiza a partir do ponto inicial da replicação.
Este é o LSN exato que deve ser usado como local de replicação
inicial para cada subscrição.
O nome da origem da replicação é obtido a partir do momento
em que a subscrição foi criada.
O nome da origem da replicação e o ponto de início da replicação
são usados na função
pg_replication_origin_advance()
Para definir o local de replicação inicial.
Ative a subscrição para cada banco de dados especificado no servidor de destino. A subscrição começa a aplicar transações a partir do ponto inicial de replicação.
Se o servidor em-espera estava usando primary_slot_name, ele não terá mais utilidade de agora em diante, então exclua-o.
Se o servidor em espera contiver encaixes de replicação de failover, eles não poderão mais ser sincronizados; portanto, remova-os.
Atualize o identificador do sistema no servidor de destino.
O utilitário pg_resetwal é executado para
modificar o identificador do sistema.
O servidor de destino é parado como requerido pelo
utilitário pg_resetwal.
Para criar uma réplica lógica para os bancos de dados
hr e finance a partir de uma
réplica física em foo:
$pg_createsubscriber -D /usr/local/pgsql/data -P "host=foo" -d hr -d finance