CREATE SUBSCRIPTION — define uma nova subscrição
CREATE SUBSCRIPTIONnome_da_subscriçãoCONNECTION 'informação_da_conexão' PUBLICATIONnome_da_publicação[, ...] [ WITH (parâmetro_de_subscrição[=valor] [, ... ] ) ]
O comando CREATE SUBSCRIPTION adiciona uma nova
subscrição de replicação lógica.
O usuário que cria uma subscrição torna-se o dono da subscrição.
O nome da subscrição deve ser diferente do nome de qualquer outra
subscrição existente no banco de dados corrente.
Uma subscrição representa uma conexão de replicação com o publicador. Portanto, além de adicionar definições nos catálogos locais, este comando normalmente cria um encaixe de replicação no publicador.
Um processo de replicação lógica será iniciado para replicar os dados da nova subscrição no momento da efetivação da transação em que este comando for executado, a menos que a subscrição esteja inicialmente desativada.
Para poder criar uma subscrição, é necessário ter os privilégios
da função de banco de dados pg_create_subscription,
bem como privilégios de CREATE no banco de dados
corrente.
Informações adicionais sobre subscrições e replicação lógica como um todo estão disponíveis em Subscrição e Replicação lógica.
nome_da_subscrição #Parâmetros
CONNECTION 'informação_da_conexão' #A cadeia de caracteres de conexão aceita pela libpq que define como conectar-se ao banco de dados publicador. Veja Cadeias de caracteres de conexão para obter detalhes.
PUBLICATION nome_da_publicação [, ...] #Nomes das publicações do publicador às quais se pode subscrever.
WITH ( parâmetro_de_subscrição [= valor] [, ... ] ) #Esta cláusula especifica parâmetros opcionais para uma subscrição.
Os seguintes parâmetros controlam o que acontece durante a criação da subscrição:
connect (boolean) #
Especifica se o comando CREATE SUBSCRIPTION
deve se conectar ao publicador.
O padrão é true.
Definir como false forçará os valores de
create_slot, enabled e
copy_data serem false.
(Não é possível combinar a definição de connect
como false com a definição de
create_slot, enabled,
ou copy_data como true.)
Como nenhuma conexão é feita quando esta opção é
false, nenhuma tabela é subscrita.
Para iniciar a replicação, se deve criar manualmente o encaixe
de replicação, ativar failover, se necessário,
ativar a subscrição e atualizar a subscrição.
Veja
Exemplos: Criação de Encaixe de Replicação Adiado
para obter exemplos.
create_slot (boolean) #
Especifica se o comando deve criar um encaixe de replicação
no publicador.
O padrão é true.
Se definido como false, você se torna
responsável por criar o espaço reservado para o publicador
de alguma outra forma.
Veja
Exemplos: Criação de Encaixe de Replicação Adiado
para obter exemplos.
enabled (boolean) #
Especifica se a subscrição deve estar sendo replicada
ativamente ou se deve apenas ser configurada, mas ainda
não iniciada.
O padrão é true.
slot_name (string) #Nome do encaixe de replicação do publicador a ser utilizado. O padrão é utilizar o nome da subscrição como nome do encaixe.
Definir slot_name como NONE
significa que não haverá nenhum encaixe de replicação
associado à subscrição.
Estas subscrições também devem ter
enabled create_slot
definidos como false.
Use esta opção quando for criar o encaixe de replicação
manualmente mais tarde.
Veja
Exemplos: Criação de Encaixe de Replicação Adiado
para obter exemplos.
Ao definir slot_name com um nome válido e
create_slot como false,
o valor da propriedade failover do encaixe
indicado pode ser diferente do parâmetro
failover correspondente especificado na
subscrição.
Sempre se deve garantir de que a propriedade
failover do encaixe corresponda ao
parâmetro correspondente da subscrição e vice-versa.
Caso contrário, o comportamento do servidor na plataforma do
publicador pode ser diferente do que indicam estas opções
de subscrição: por exemplo, o encaixe no servidor de publicação
pode ser sincronizado com os servidores em espera mesmo quando
a opção failover da subscrição estiver
desativada, ou pode ser desativado para sincronização mesmo
quando a opção failover da subscrição
estiver ativa.
Os seguintes parâmetros controlam o comportamento de replicação da subscrição após sua criação:
binary (boolean) #
Especifica se a subscrição solicitará ao publicador que envie
os dados em formato binário (em vez de texto).
O padrão é false.
Qualquer cópia inicial de sincronização de tabela
(veja copy_data) também usa o mesmo formato.
O formato binário pode ser mais rápido que o formato de texto,
mas é menos portável entre diferentes arquiteturas de máquinas
e versões do PostgreSQL.
O formato binário é muito específico para cada tipo de dados;
por exemplo, não irá permitir copiar de uma coluna
smallint para uma coluna integer,
embora isto funcione perfeitamente em formato de texto.
Mesmo quando esta opção está ativa, somente os tipos de dados
que possuem funções de envio e recebimento binárias serão
transferidos em formato binário.
Note que a sincronização inicial exige que todos os tipos de
dados possuam funções binárias de envio e recebimento;
caso contrário, a sincronização irá falhar.
(veja CREATE TYPE para obter mais
informações sobre as funções de envio/recebimento).
Ao realizar a replicação entre versões, pode acontecer que
o publicador tenha uma função de envio binária para determinado
tipo de dados, mas o subscritor não possua uma função de
recebimento binária para este tipo de dados.
Neste caso, a transferência de dados irá falhará e a opção
binária não poderá ser usada.
Se o publicador for de uma versão do
PostgreSQL anterior à 16,
qualquer sincronização inicial da tabela usará o formato
de texto, mesmo que binary = true.
copy_data (boolean) #
Especifica se os dados preexistentes nas publicações às quais
a replicação está subscrita devem ser copiados no início da
replicação.
O padrão é true.
Se as publicações contiverem cláusulas WHERE,
isto afetará os dados que serão copiados.
Veja Notas
para obter detalhes.
Veja Notas
para obter detalhes sobre como
copy_data = true pode interagir com o
parâmetro origin.
streaming (enum) #
Especifica se deve ser possível ativar o fluxo
(streaming) de transações
em andamento para esta subscrição.
O valor padrão é parallel,
significando que as novas alterações são aplicadas
diretamente por meio de um dos processos trabalhadores de
aplicação em paralelo, se disponíveis.
Se nenhum processo trabalhador de aplicação em paralelo estiver
livre para lidar com transações de fluxo, as alterações serão
escritas em arquivos temporários e aplicadas após a efetivação
da transação.
Note que, se ocorrer um erro em um processo trabalhador de
aplicação em paralelo, o LSN de conclusão
da transação remota pode não ser registrado no
WAL do servidor.
Existe o risco de impasse quando os esquemas do publicador e do subscritor são diferentes, embora estes casos sejam raros. O processo trabalhador de aplicação está equipado para repetir estas transações automaticamente.
Se definido como on, as alterações recebidas
são gravadas em arquivos temporários e aplicadas somente após
a transação ser efetivada no publicador e recebida pelo
subscritor.
Se definido como off, todas as transações
são totalmente decodificadas no publicador e somente então
enviadas ao subscritor como um todo.
synchronous_commit (enum) #
O valor desse parâmetro se sobrepõe a configuração
synchronous_commit nos processos
trabalhadores de aplicação desta subscrição.
O valor padrão é off.
É seguro usar off para replicação lógica:
se o subscritor perder transações devido à falta de
sincronização, os dados serão enviados novamente pelo publicador.
Pode ser apropriada uma configuração diferente ao fazer
a replicação lógica síncrona.
Os operadores de replicação lógica informam as posições de
escrita e liberação para o publicador e, ao usar a replicação
síncrona, o publicador aguardará a liberação real.
Isto significa que definir synchronous_commit
para o subscritor como off, quando a
subscrição é usada para replicação síncrona, pode aumentar a
latência para o COMMIT no publicador.
Neste cenário, pode ser vantajoso definir
synchronous_commit como
local, ou mais alto.
two_phase (boolean) #
Especifica se a efetivação em duas fases estará ativa para
esta subscrição.
O padrão é false.
Quando a efetivação em duas fases está ativa, as transações
preparadas são enviadas ao subscritor no momento do
PREPARE TRANSACTION, e também são
processadas como transações de duas fases para o subscritor.
Caso contrário, as transações preparadas são enviadas ao
subscritor somente após serem efetivadas e, em seguida,
são processadas imediatamente por ele.
A implementação da efetivação em duas fases requer que a
replicação tenha terminado com sucesso a fase inicial de
sincronização da tabela.
Então, mesmo quando a efetivação em duas fases está ativa para
uma subscrição, o estado interno das duas fases permanece
temporariamente “pendente” até que a fase de
inicialização seja concluída.
Veja a coluna subtwophasestate de
pg_subscription
para conhecer o estado das duas fases.
disable_on_error (boolean) #
Especifica se a subscrição deve ser desativada automaticamente
caso sejam detectados erros pelos processos de subscrição
durante a replicação de dados do publicador.
O padrão é false.
password_required (boolean) #
Se definido como true, as conexões com o
publicador feitas como resultado desta subscrição devem usar
autenticação por senha e a senha deve ser especificada como
parte da cadeia de caracteres de conexão.
Esta definição é ignorada quando a subscrição pertence
a um superusuário.
O padrão é true.
Somente superusuários podem definir este valor como
false.
run_as_owner (boolean) #
Se definido como verdade, todas as ações de replicação serão
executadas como sendo o dono da subscrição.
Se definido como falso, os processos de replicação executarão
ações em cada tabela como sendo o dono dessa tabela.
A última configuração é geralmente muito mais segura;
para obter mais detalhes, veja
Segurança.
O padrão é false.
origin (string) #
Especifica se a subscrição irá solicitar ao publicador que
envie apenas as alterações que não possuem uma origem definida,
ou que envie as alterações independentemente da origem.
Definir origin como none
significa que a subscrição irá solicitar ao publicador que
envie apenas as alterações que não possuem uma origem definida.
Definir origin como any
significa que o publicador envia as alterações
independentemente de sua origem.
O padrão é any.
Veja Notas para
obter detalhes sobre como copy_data = true
pode interagir com o parâmetro origin.
failover (boolean) #
Especifica se os encaixes de replicação associados à subscrição
estão habilitados para serem sincronizados com os servidores
em espera, de modo que a replicação lógica possa ser retomada
a partir do novo servidor primário após a falha.
O padrão é false.
Ao especificar um parâmetro do tipo de dados boolean,
então a parte
= valor
pode ser omitida, o que é equivalente a especificar
true.
Veja Segurança para obter detalhes sobre como configurar o controle de acesso entre a subscrição e a instância de publicação.
Ao criar um encaixe de replicação (o comportamento padrão),
o comando CREATE SUBSCRIPTION não pode ser
executado em um bloco de transação.
Ao criar uma subscrição que se conecta ao mesmo agrupamento de bancos
de dados (instância) (por exemplo, para replicar entre bancos de dados
na mesma instância, ou para replicar dentro do mesmo banco de dados)
só haverá sucesso se o encaixe de replicação não for criado como parte
do mesmo comando.
Caso contrário, a execução de CREATE SUBSCRIPTION
irá travar.
Para fazer com que isto funcione, deve-se criar o encaixe de
replicação separadamente (usando a função
pg_create_logical_replication_slot com o nome
do plug-in pgoutput), e criar a subscrição usando
o parâmetro create_slot = false.
Veja
Exemplos: Criação de Encaixe de Replicação Adiado.
Esta é uma restrição de implementação que poderá ser removida
em uma versão futura.
Se alguma tabela na publicação tiver uma cláusula WHERE,
as linhas para as quais a expressão
for avaliada como falsa ou NULL não serão publicadas.
Se a subscrição tiver várias publicações nas quais a mesma tabela
foi publicada com diferentes cláusulas WHERE,
a linha será publicada se alguma das expressões (referentes àquela
operação de publicação) for satisfeita.
No caso de cláusulas WHERE diferentes,
se uma das publicações não tiver uma cláusula WHERE
(referindo-se àquela operação de publicação) ou a publicação for
declarada como FOR ALL TABLES
ou FOR TABLES IN SCHEMA,
as linhas serão sempre publicadas, independentemente da definição
das outras expressões.
Se o subscritor estiver usando uma versão do
PostgreSQL anterior à 15, qualquer
filtragem de linhas será ignorada durante a fase inicial de
sincronização de dados.
Neste caso, o usuário pode considerar excluir quaisquer dados
copiados inicialmente que sejam incompatíveis com a filtragem
subsequente.
Como a sincronização inicial de dados não leva em consideração
o parâmetro publish
ao copiar dados de tabelas existentes, algumas linhas podem ser
copiadas que não seriam replicadas usando DML.
Veja Exemplos: Definir replicação lógica.
Subscrições com várias publicações nas quais a mesma tabela foi publicada com listas de colunas diferentes não têm suporte.
É permitido que sejam especificadas publicações inexistentes para que os usuários possam adicioná-las posteriormente. Isto significa que pg_subscription pode ter publicações inexistentes.
Ao usar uma combinação de parâmetros de subscrição
copy_data = true e origin = NONE,
os dados da tabela de sincronização inicial são copiados diretamente
do publicador, significando não ser possível conhecer a verdadeira
origem desses dados.
Se o publicador também tiver subscrições , os dados da tabela
copiados podem ter se originado de uma fonte anterior na cadeia
de transmissão.
Este cenário é detectado e um WARNING é registrado
para o usuário, mas a advertência é apenas uma indicação de um
problema potencial;
É responsabilidade do usuário realizar as verificações necessárias
para garantir que a origem dos dados copiados seja realmente
a desejada.
Para descobrir quais tabelas podem potencialmente incluir origens não locais (devido a outras subscrições criadas no publicador), pode-se tentar usar esta consulta SQL:
# substitua <pub-names> abaixo pelo(s) nome(s)
# da(s) sua(s) publicação(ões) a serem consultadas.
SELECT DISTINCT PT.schemaname, PT.tablename
FROM pg_publication_tables PT
JOIN pg_class C ON (C.relname = PT.tablename)
JOIN pg_namespace N ON (N.nspname = PT.schemaname),
pg_subscription_rel PS
WHERE C.relnamespace = N.oid AND
(PS.srrelid = C.oid OR
C.oid IN (SELECT relid FROM pg_partition_ancestors(PS.srrelid) UNION
SELECT relid FROM pg_partition_tree(PS.srrelid))) AND
PT.pubname IN (<pub-names>);
Criar uma subscrição para um servidor remoto que replique tabelas
nas publicações minha_publicação e
inserir_apenas, e começar a replicar imediatamente
na efetivação:
CREATE SUBSCRIPTION minha_subscrição
CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
PUBLICATION minha_publicação, inserir_apenas;
Criar uma subscrição para um servidor remoto que replique tabelas na
publicação inserir_apenas, e não comece a replicar
até ser ativado posteriormente.
CREATE SUBSCRIPTION minha_subscrição
CONNECTION 'host=192.168.1.50 port=5432 user=foo dbname=foodb'
PUBLICATION inserir_apenas
WITH (enabled = false);
O comando CREATE SUBSCRIPTION é uma extensão do
PostgreSQL.