Resolução de problemas de ingestão no PostgreSQL

Esta página descreve os problemas comuns com o conector PostgreSQL no Databricks Lakeflow Connect e como os resolver.

Solução de problemas gerais de canalização

As etapas de solução de problemas nesta seção se aplicam a todos os pipelines de ingestão no Lakeflow Connect.

Se um pipeline falhar durante a execução, clique no passo que falhou e confirme se a mensagem de erro fornece informação suficiente sobre a natureza do erro.

Você também pode verificar e baixar os logs do cluster na página de detalhes do pipeline clicando em Atualizar detalhes no painel direito e, em seguida, em Logs. Analise os logs em busca de erros ou exceções.

Solução de problemas específica para conectores

Os passos de resolução de problemas nesta secção são específicos do conector PostgreSQL.

Erros de permissão

Se receber um erro de permissão, verifique se o utilizador de replicação tem os privilégios necessários. Consulte os requisitos do utilizador da base de dados PostgreSQL para a lista completa de privilégios exigidos.

ERRO: permissão negada para tabela

Este erro indica que o utilizador de replicação não tem SELECT privilégios na tabela especificada. Conceda os privilégios necessários:

GRANT SELECT ON TABLE schema_name.table_name TO databricks_replication;

ERRO: deve ser superutilizador ou função de replicação para usar slots de replicação

Este erro indica que o utilizador de replicação não tem esse REPLICATION privilégio. Conceda a função de replicação:

-- For standard PostgreSQL
ALTER USER databricks_replication WITH REPLICATION;

-- For AWS RDS/Aurora
GRANT rds_replication TO databricks_replication;

-- For GCP Cloud SQL
ALTER USER databricks_replication with REPLICATION;

Verifique se a replicação lógica está ativada

Para verificar se a replicação lógica está ativada:

SHOW wal_level;

A saída deve ser logical. Se não estiver, atualiza o wal_level parâmetro e reinicia o servidor PostgreSQL.

Para PostgreSQL gerido na cloud:

• AWS RDS/Aurora: Defina rds.logical_replication como 1 no grupo de parâmetros.
• Azure Database para PostgreSQL: Permitir a replicação lógica nos parâmetros do servidor.
• GCP Cloud SQL: Defina a cloudsql.logical_decoding flag para on.

Verifique se existe uma publicação

Para verificar se existe uma publicação para as suas tabelas:

SELECT * FROM pg_publication WHERE pubname = 'databricks_publication';

-- Check which tables are included in the publication
SELECT schemaname, tablename
FROM pg_publication_tables
WHERE pubname = 'databricks_publication';

Se a publicação não existir, crie-a:

CREATE PUBLICATION databricks_publication FOR TABLE schema_name.table_name;

Verificar a identidade da réplica

Para verificar a configuração de identidade da réplica para uma tabela:

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

A relreplident coluna deve mostrar os seguintes valores:

• f para identidade de réplica COMPLETA (necessária para tabelas sem chaves primárias ou colunas TOAST).
• d para a identidade de réplica padrão (usa a chave primária).

Se a identidade da réplica não estiver definida corretamente, atualize-a:

ALTER TABLE schema_name.table_name REPLICA IDENTITY FULL;

Erros de slot de replicação

Problemas de acumulação de WAL e de espaço em disco

Se o gateway de ingestão for parado por um período prolongado, o slot de replicação pode causar a acumulação de ficheiros de Write-Ahead Log (WAL), potencialmente preenchendo espaço em disco.

Para verificar a utilização do disco WAL:

SELECT pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS retained_wal
FROM pg_replication_slots
WHERE slot_name = 'your_slot_name';

Para evitar o acúmulo de WAL:

1. Garanta que o gateway de ingestão está a funcionar continuamente.
2. Monitorize regularmente o atraso na replicação e o espaço em disco.

Se os ficheiros WAL se acumularem, pode retirar manualmente o slot de replicação:

SELECT pg_drop_replication_slot('your_slot_name');

Tempo limite enquanto se espera pelo token da mesa

O fluxo de ingestão pode ultrapassar o tempo limite enquanto aguarda que o gateway forneça as informações. Isto pode dever-se a uma das seguintes razões:

• Você está executando uma versão mais antiga do gateway.
• Houve um erro ao gerar as informações necessárias. Verifique se há erros nos logs do driver do gateway.
• A fotografia inicial está a demorar mais do que o esperado. Para tabelas grandes, considere aumentar o timeout do pipeline ou executar a carga inicial durante as horas de menor afluência.

Conflito de nomenclatura da tabela de origem

Ingestion pipeline error: "org.apache.spark.sql.catalyst.ExtendedAnalysisException: Cannot have multiple queries named `orders_snapshot_load` for `orders`. Additional queries on that table must be named. Note that unnamed queries default to the same name as the table.

Isso indica que há um conflito de nome devido a várias tabelas de origem nomeadas orders em esquemas de origem diferentes que estão a ser ingeridas pelo mesmo pipeline de ingestão num mesmo esquema de destino.

Crie múltiplos pares de gateway-pipeline, escrevendo essas tabelas conflitantes em diferentes esquemas de destino.

Alterações de esquema incompatíveis

Uma alteração de esquema incompatível faz com que o pipeline de ingestão falhe com um erro INCOMPATIBLE_SCHEMA_CHANGE. Para continuar a replicação, acione uma atualização completa das tabelas afetadas.

Alterações de esquema incompatíveis incluem as seguintes:

• Alterar o tipo de dados de uma coluna
• Renomear uma coluna
• Alterar a chave primária de uma tabela
• Eliminar uma coluna que faz parte da identidade da réplica

Erros de tempo limite da ligação

Se receber erros de tempo limite de ligação, realize as seguintes verificações:

1. Verifique se as regras do firewall permitem ligações a partir do espaço de trabalho Databricks.
2. Verifique se o servidor PostgreSQL é acessível a partir da rede Databricks.
3. Certifique-se de que o pg_hba.conf ficheiro permite ligações a partir da faixa IP do Databricks.
4. Verifica se as credenciais de ligação estão corretas.

Erros de ligação SSL/TLS

Se receber erros de ligação SSL/TLS, realize as seguintes verificações:

1. Verifique se o servidor PostgreSQL suporta ligações SSL.

2. Verifique o ssl parâmetro na configuração do PostgreSQL:

   SHOW ssl;
   

3. Certifique-se de que o pg_hba.conf ficheiro requer ou permite ligações SSL para o utilizador de replicação.

4. Para bases de dados geridas na cloud, verifique se o SSL está aplicado nas definições do servidor.

Autenticação padrão: não é possível configurar credenciais padrão

Se você receber esse erro, há um problema com a descoberta das credenciais de usuário atuais. Tente substituir o seguinte:

w = WorkspaceClient()

com:

w = WorkspaceClient(host=input('Databricks Workspace URL: '), token=input('Token: '))

Consulte Autenticação na documentação do Databricks SDK for Python.

PERMISSION_DENIED: Você não está autorizado a criar clusters. Contacte o seu administrador.

Entre em contato com um administrador de conta Databricks para conceder permissões Unrestricted cluster creation.

CÓDIGO DE ERRO DLT: ERRO INTERNO DO PORTAL DE INGESTÃO

Verifique os stdout ficheiros nos registos de drivers para mensagens de erro detalhadas. As causas comuns incluem as seguintes:

• Erros de slot de replicação
• Problemas de configuração da publicação
• Problemas de conectividade de rede
• Privilégios insuficientes na base de dados de origem

Erros de certificado do servidor TLS

Para resolução de erros de validação de certificados do servidor TLS, veja Solucionar erros de certificados TLS.