Configurar o PostgreSQL para ingestão no Databricks

info

Visualização

O conector PostgreSQL para LakeFlow Connect está em versão prévia pública. Entre em contato com a equipe da sua account Databricks para se inscrever na Prévia Pública.

Esta página descreve a tarefa de configuração da origem para ingestão de dados do PostgreSQL no Databricks usando LakeFlow Connect.

Replicação lógica para captura de dados de alterações (CDC)

O conector PostgreSQL usa replicação lógica para rastrear alterações nas tabelas de origem. A replicação lógica permite que o conector capture modificações de dados (inserções, atualizações e exclusões) sem exigir gatilhos ou sobrecarga significativa no banco de dados de origem.

A replicação lógica LakeFlow PostgreSQL requer o seguinte:

1. LakeFlow Connect suporta a replicação de dados do PostgreSQL versão 13 e posteriores.

2. Configure o banco de dados para replicação lógica:

   O parâmetro PostgreSQL wal_level deve ser definido como logical.

3. Crie publicações que incluam todas as tabelas que você deseja replicar.

4. Crie slots de replicação para cada catálogo que será replicado.

nota

As publicações devem ser criadas antes da criação dos espaços de replicação.

Para obter mais informações sobre replicação lógica, consulte a documentação sobre Replicação Lógica no site PostgreSQL .

Visão geral da tarefa de configuração da fonte

Conclua a seguinte tarefa no PostgreSQL antes de ingerir os dados no Databricks:

1. Verifique se PostgreSQL é versão 13 ou superior.

2. Configure o acesso à rede (grupos de segurança, regras de firewall ou VPN).

3. Configurar replicação lógica:

   • Ativar replicação lógica (wal_level = logical)

   • Crie um usuário de replicação com os privilégios necessários. Consulte os requisitos de usuário do banco de dados PostgreSQL.

   • Defina a identidade da réplica para as tabelas. Consulte Definir identidade de réplica para tabelas

   • Criação de publicações e espaços para replicação

4. Opcional: Configure o acompanhamento DDL embutido para detecção automática de alterações de esquema. Caso prefira o acompanhamento DDL embutido, entre em contato com o suporte Databricks .

importante

Se você planeja replicar dados de vários bancos de dados PostgreSQL, deverá criar um slot de publicação e um slot de replicação separados para cada banco de dados. O script de acompanhamento DDL embutido (se utilizado) também deve ser executado em cada banco de dados.

Configurar replicação lógica

Para habilitar a replicação lógica no PostgreSQL, configure as definições do banco de dados e defina os objetos necessários.

Defina o nível WAL para lógico.

O Write-Ahead Log (WAL) deve ser configurado para replicação lógica. Essa configuração normalmente requer a reinicialização do banco de dados.

1. Verifique a configuração atual wal_level :

   SQL

   SHOW wal_level;

2. Se o valor não for logical, defina wal_level = logical na configuração do servidor e reinicie o serviço PostgreSQL.

Criar um usuário de replicação

Crie um usuário dedicado para ingestão de dados no Databricks com privilégios de replicação:

SQL

CREATE USER databricks_replication WITH PASSWORD 'your_secure_password';
GRANT CONNECT ON DATABASE your_database TO databricks_replication;
ALTER USER databricks_replication WITH REPLICATION;

Para obter informações detalhadas sobre os requisitos de privilégio, consulte os requisitos de usuário do banco de dados PostgreSQL.

Defina a identidade da réplica para as tabelas.

Para cada tabela que você deseja replicar, configure a identidade da réplica. A configuração correta depende da estrutura da tabela:

Estrutura da tabela	IDENTIDADE DE RÉPLICA OBRIGATÓRIA	Comando
A tabela possui key primária e não contém colunas TOASTable (por exemplo, TEXT, BYTEA, VARCHAR(n) com valores grandes).	DEFAULT
A tabela possui key primária, mas inclui colunas grandes de comprimento variável (TOASTable).	FULL
A tabela não possui keyprimária.	FULL

Para obter mais informações sobre as configurações de identidade de réplica, consulte Identidade de Réplica na documentação PostgreSQL .

Criar uma publicação

Crie uma publicação em cada banco de dados que inclua as tabelas que você deseja replicar:

SQL

-- Create a publication for specific tables
CREATE PUBLICATION databricks_publication FOR TABLE schema_name.table1, schema_name.table2;

-- Or create a publication for all tables in a database
CREATE PUBLICATION databricks_publication FOR ALL TABLES;

nota

Você deve criar uma publicação separada em cada banco de dados PostgreSQL que deseja replicar.

Configurar parâmetros de slot de replicação

Antes de criar slots de replicação, configure os seguintes parâmetros do servidor:

Limitar a retenção de WAL para slots de replicação

Parâmetro : max_slot_wal_keep_size

É recomendável não definir max_slot_wal_keep_size como -1 (o valor default ), pois isso permite um inchaço ilimitado do WAL devido à retenção por slots de replicação atrasados ou inativos. Dependendo da sua carga de trabalho, defina este parâmetro com um valor finito.

Saiba mais sobre o parâmetro max_slot_wal_keep_size na documentação oficial do PostgreSQL.

nota

Alguns provedores cloud gerenciada não permitem a modificação desse parâmetro e, em vez disso, dependem do monitoramento de slots integrado e da limpeza automática. Analise o comportamento da plataforma antes de configurar um alerta operacional.

Para saber mais, consulte:

• Controlando o crescimento do arquivo WAL do PostgreSQL - pgDash
• PostgreSQL 13: Não deixe que os slots destruam seu servidor primário | EDB

Configurar capacidade de slots de replicação

Parâmetro : max_replication_slots

Cada banco de dados PostgreSQL que está sendo replicado requer um slot de replicação lógica. Defina este parâmetro para, no mínimo, o número de bancos de dados que estão sendo replicados, mais quaisquer necessidades de replicação existentes.

Configurar remetentes WAL

Parâmetro : max_wal_senders

Este parâmetro define o número máximo de processos de envio WAL simultâneos que transmitem dados WAL aos assinantes. Na maioria dos casos, você deve ter um processo de envio de WAL para cada slot de replicação para garantir uma replicação de dados eficiente e consistente.

Configure max_wal_senders para ser pelo menos igual ao número de slots de replicação em uso, levando em consideração qualquer outro uso existente. Recomenda-se definir um valor ligeiramente superior para proporcionar flexibilidade operacional.

Crie um slot de replicação

Crie um slot de replicação em cada banco de dados que o gateway de ingestão do Databricks usará para rastrear as alterações:

SQL

-- Create a replication slot with the pgoutput plugin
SELECT pg_create_logical_replication_slot('databricks_slot', 'pgoutput');

importante

• Os slots de replicação armazenam dados WAL até que sejam consumidos pelo conector. Configure o parâmetro max_slot_wal_keep_size para limitar a retenção de WAL e evitar o crescimento ilimitado de WAL. Consulte a seção Configurar parâmetros do slot de replicação para obter detalhes.
• Ao excluir um pipeline de ingestão, você deve remover manualmente o slot de replicação associado. Consulte Limpar slots de replicação.

Opcional: Configurar acompanhamento DDL in-line

O acompanhamento DDL embutido é um recurso opcional que permite ao conector detectar e aplicar automaticamente as alterações de esquema do banco de dados de origem. Este recurso está desativado por default.

atenção

O acompanhamento DDL embutido está atualmente em versão prévia e requer contato com o Suporte Databricks para habilitá-lo em seu workspace.

Para obter informações sobre quais alterações de esquema são tratadas automaticamente e quais requerem uma refresh completa, consulte Como gerenciar conectores lidam com a evolução do esquema? e evolução do esquema.

Configurar acompanhamento DDL inline

Se o acompanhamento DDL embutido estiver habilitado para seu workspace, conclua estas etapas em cada banco de dados PostgreSQL :

1. Baixe e execute o script lakeflow_pg_ddl_change_tracking.sql :

   SQL

   \i lakeflow_pg_ddl_change_tracking.sql

2. Verifique se os gatilhos e a tabela de auditoria foram criados com sucesso:

   SQL

   -- Check for the DDL audit table
   SELECT * FROM pg_tables WHERE tablename = 'lakeflow_ddl_audit';
   
   -- Check for the event triggers
   SELECT * FROM pg_event_trigger WHERE evtname LIKE 'lakeflow%';

3. Adicione a tabela de auditoria DDL à sua publicação:

   SQL

   ALTER PUBLICATION databricks_publication ADD TABLE public.lakeflow_ddl_audit;

notas de configuração específicas da nuvem

AWS RDS e Aurora

• Certifique-se de que o parâmetro rds.logical_replication esteja definido como 1 no grupo de parâmetros.

• Configure os grupos de segurança para permitir conexões do workspace Databricks .

• O usuário de replicação requer a função rds_replication :

  SQL

  GRANT rds_replication TO databricks_replication;

Banco de Dados do Azure para PostgreSQL

• Habilite a replicação lógica nos parâmetros do servidor por meio do portal do Azure ou da CLI.
• Configure as regras do firewall para permitir conexões do workspace Databricks .
• Para o Flexible Server, a replicação lógica é suportada. Para servidores individuais, certifique-se de estar usando um plano compatível.

GCP Cloud SQL para PostgreSQL

• Ative a flag cloudsql.logical_decoding nas configurações da instância.
• Configure as redes autorizadas para permitir conexões do workspace Databricks .
• Certifique-se de que o sinalizador cloudsql.enable_pglogical esteja definido como on se estiver usando extensões pglogical.

Verifique a configuração

Após concluir a tarefa de configuração, verifique se a replicação lógica está configurada corretamente:

1. Verifique se wal_level está definido como logical:

   SQL

   SHOW wal_level;

2. Verifique se o usuário de replicação possui o privilégio replication :

   SQL

   SELECT rolname, rolreplication FROM pg_roles WHERE rolname = 'databricks_replication';

3. Confirme se a publicação existe:

   SQL

   SELECT * FROM pg_publication WHERE pubname = 'databricks_publication';

4. Verifique se o slot de replicação existe:

   SQL

   SELECT slot_name, slot_type, active, restart_lsn
   FROM pg_replication_slots
   WHERE slot_name = 'databricks_slot';

5. Verifique a identidade da réplica das suas tabelas:

   SQL

   SELECT schemaname, tablename, relreplident
   FROM pg_tables t
   JOIN pg_class c ON t.tablename = c.relname
   WHERE schemaname = 'your_schema';

   A coluna relreplident deve mostrar f para identidade de réplica COMPLETA.

Próximos passos

Após concluir a configuração da fonte, você pode criar um gateway de ingestão e um pipeline para ingerir dados do PostgreSQL. Consulte Ingerir dados do PostgreSQL.