Configurar o PostgreSQL para ingestão no Azure Databricks

Esta página descreve as tarefas de configuração de origem para ingestão do PostgreSQL no Azure Databricks usando o Lakeflow Connect.

Credenciais usadas durante a instalação e ingestão

A ingestão de PostgreSQL usa dois conjuntos diferentes de credenciais em dois estágios diferentes. Saber quais credenciais usar onde impede erros de autenticação e permissão durante a instalação.

Replicação lógica para captura de dados de alteração

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

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

1. O Lakeflow Connect dá suporte à replicação de dados do PostgreSQL versão 13 e posterior.

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

   O parâmetro wal_level PostgreSQL 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.

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

Visão geral das tarefas de configuração de origem

Conclua as seguintes tarefas no PostgreSQL antes de ingerir dados no Azure Databricks:

1. Verificar o PostgreSQL 13 ou superior

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

3. Configurar a replicação lógica:

   • Habilitar replicação lógica (wal_level = logical)
   • Crie um usuário de replicação com privilégios necessários. Consulte os requisitos de usuário do banco de dados PostgreSQL
   • Definir identidade de réplica nas tabelas. Consulte Definir identidade de réplica para tabelas
   • Criando publicações e slots de replicação

4. Opcional: configure o acompanhamento de DDL embutido para detecção automática de alterações de esquema. Caso deseje optar pelo rastreamento de DDL inline, entre em contato com o suporte do Databricks.

Configurar a replicação lógica

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

Definir o nível WAL como lógico

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

1. Verifique a configuração atual wal_level :

   SHOW wal_level;
   

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

Criar um usuário de replicação

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

CREATE USER databricks_replication WITH PASSWORD 'your_secure_password';
GRANT CONNECT ON DATABASE your_database TO databricks_replication;
GRANT USAGE ON SCHEMA schema_name TO databricks_replication;
GRANT SELECT ON TABLE schema_name.table_name TO databricks_replication;
ALTER USER databricks_replication WITH REPLICATION;

Para obter requisitos de privilégio detalhados, consulte os requisitos de usuário do banco de dados PostgreSQL.

Definir a identidade da réplica para tabelas

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

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

Criar uma publicação

Crie uma publicação em cada banco de dados que inclua as tabelas que você deseja replicar. Execute este comando como o proprietário da tabela ou um superusuário:

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

Configurar parâmetros de slot de replicação

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

Limitar a retenção do 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 padrão), pois isso permite uma sobrecarga de WAL não associada devido à retenção por slots de replicação inativos ou atrasados. Dependendo da carga de trabalho, defina esse parâmetro como um valor finito.

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

Configurar a capacidade do slot 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 esse parâmetro como pelo menos o número de bancos de dados que estão sendo replicados, além de quaisquer necessidades de replicação existentes.

Configurar remetentes do WAL

Parâmetro: max_wal_senders

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

Configure max_wal_senders para ser pelo menos igual ao número de slots de replicação em uso, contabilizando qualquer outro uso existente. É recomendável defini-lo um pouco mais alto para fornecer flexibilidade operacional.

Criar 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 controlar as alterações. O slot de replicação deve ser criado por um usuário com o REPLICATION privilégio. Se você estiver conectado como um superusuário ou administrador, alterne primeiro para o usuário de replicação:

SET ROLE databricks_replication;

-- Databricks supports only the pgoutput plugin for replication slots
SELECT pg_create_logical_replication_slot('databricks_slot', 'pgoutput');

-- Switch back to the admin or table owner role for subsequent steps
RESET ROLE;

Opcional: configurar o acompanhamento de DDL embutido

O rastreamento de DDL embutido é um recurso opcional que permite a um conector detectar e aplicar automaticamente alterações de esquema do banco de dados de origem. Esta funcionalidade está desativada por predefinição.

Para obter informações sobre quais alterações de esquema são tratadas automaticamente e quais exigem uma atualização completa, confira Como os conectores gerenciados lidam com a evolução do esquema? e a evolução do esquema.

Configurar o monitoramento de DDL em linha

Você pode completar a configuração do lado da fonte abaixo com antecedência para que o rastreamento DDL inline esteja pronto para uso assim que o recurso for ativado para seu espaço de trabalho. Criar os objetos de auditoria não tem efeito no conector até que o recurso seja ativado, então é seguro executar essas etapas com antecedência.

Complete estes passos em cada banco de dados PostgreSQL:

1. Baixe a versão mais recente do script:

   Baixar lakeflow_pg_ddl_change_tracking.sql

2. Executar o script:

   \i lakeflow_pg_ddl_change_tracking.sql
   

   O script cria os seguintes objetos no public esquema. Os nomes de objeto incluem um sufixo de versão (atualmente _1_0) que rastreia a versão do script:

   • Tabela de auditoria: public.lakeflow_ddl_audit_table_1_0 — armazena eventos DDL capturados.
   • Funções de gatilho de eventos: public.lakeflow_ddl_audit_function_1_0 (para eventos ALTER TABLE) e public.lakeflow_drop_ddl_audit_function_1_0 (para eventos DROP TABLE).
   • Gatilhos de evento: lakeflow_ddl_audit_trigger_1_0 (é acionado em ddl_command_end) e lakeflow_drop_ddl_audit_trigger_1_0 (é acionado em sql_drop).

3. Verifique se os gatilhos e a tabela de auditoria foram criados com êxito:

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

   Você deve ver a tabela lakeflow_ddl_audit_table_1_0 de auditoria e dois gatilhos de evento (lakeflow_ddl_audit_trigger_1_0 e lakeflow_drop_ddl_audit_trigger_1_0).

4. Adicione a tabela de auditoria DDL à sua publicação. Esse comando deve ser executado como o proprietário da publicação, não como o usuário de replicação:

   ALTER PUBLICATION databricks_publication ADD TABLE public.lakeflow_ddl_audit_table_1_0;
   

Notas de configuração específicas da nuvem

AWS RDS e Aurora

• Verifique se o parâmetro rds.logical_replication está definido como 1 no grupo de parâmetros.

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

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

  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 de firewall para permitir conexões do workspace do Databricks.
• Para o Servidor Flexível, há suporte para replicação lógica. Para o Servidor Único, verifique se você está usando uma camada com suporte.

SQL de Nuvem do GCP para PostgreSQL

• Habilite o cloudsql.logical_decoding sinalizador nas configurações da instância.
• Configure redes autorizadas para permitir conexões do workspace do Databricks.
• Verifique se o cloudsql.enable_pglogical sinalizador está definido para on se estiver usando extensões pglogical.

Verificar a configuração

Depois de concluir as tarefas de instalação, verifique se a replicação lógica está configurada corretamente:

1. Verifique se wal_level está configurado para logical:

   SHOW wal_level;
   

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

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

3. Verifique se o usuário de replicação tem SELECT privilégios em suas tabelas. Substitua schema_name.table_name pelo esquema e pela tabela que você está replicando (por exemplo, public.my_table):

   SELECT has_table_privilege('databricks_replication', 'schema_name.table_name', 'SELECT');
   

4. Confirme se a publicação existe:

   SELECT * FROM pg_publication WHERE pubname = 'databricks_publication';
   

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

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

6. Verifique a identidade da réplica para suas tabelas:

   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 d para a identidade de réplica DEFAULT (usa a chave primária) ou f para a identidade de réplica FULL (necessária para tabelas sem chaves primárias ou com colunas TOASTable).

Próximas etapas

Depois de concluir a configuração de origem, você pode criar um gateway de ingestão e um pipeline para ingerir dados do PostgreSQL. Consulte os dados de ingestão do PostgreSQL.