Solucionar problemas de ingestão do SQL Server

Esta página descreve problemas comuns com o conector do Microsoft SQL Server no Databricks Lakeflow Connect e como resolvê-los.

Para obter diretrizes gerais de solução de problemas que se aplicam a todos os pipelines de ingestão gerenciados, consulte Solucionar problemas de pipelines de ingestão gerenciada.

Verificar se o CDC está habilitado para um banco de dados ou uma tabela

Para verificar se o CDC está habilitado para o banco de dados <database-name>:

select is_cdc_enabled from sys.databases where name='<database-name>';

Para verificar se o CDC está habilitado para a tabela <schema-name>.<table-name>:

select t.is_tracked_by_cdc
from sys.tables t join sys.schemas s on t.schema_id = s.schema_id
where s.name='<schema-name>' and t.name='<table-name>';

Verificar se o controle de alterações está habilitado para um banco de dados ou uma tabela

Para verificar se o controle de alterações está habilitado para o banco de dados \<database-name\>:

select ctdb.*

from sys.change_tracking_databases ctdb join sys.databases db

    on db.database_id  = ctdb.database_id

where db.name = '<MyDatabaseName>'

Para verificar se o controle de alterações está habilitado para a tabela <schema-name>.<table-name>:

select s.name schema_name, t.name table_name, ct.*

from sys.change_tracking_tables ct join sys.tables t

    on ct.object_id = t.object_id

    join sys.schemas s on t.schema_id = s.schema_id

where s.name = '<MySchemaName>' and t.name = '<MyTableName>'

Tempo limite para aguardar o token de tabela

O pipeline de ingestão pode atingir o tempo limite enquanto aguarda as informações a serem fornecidas pelo gateway. Isso pode ocorrer porque:

• Você está executando uma versão mais antiga do gateway.
• Ocorreu um erro ao gerar as informações necessárias. Verifique se há erros nos logs do driver do gateway.

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

Se você receber esse erro, haverá um problema ao descobrir as credenciais do usuário atual. Tente substituir o seguinte:

w = WorkspaceClient()

por:

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

Veja Autenticação na documentação do SDK do Databricks para Python.

tech.replicant.common.ExtractorException: com.microsoft.sqlserver.jdbc.SQLServerException: Nome da coluna inválido 'SERIAL_NUMBER'.

Você poderá receber esse erro se estiver usando uma versão mais antiga de uma tabela interna. Execute o seguinte no banco de dados conectado:

drop table dbo.replicate_io_audit_ddl_trigger_1;

PERMISSION_DENIED: você não tem autorização para criar clusters. Entre em contato com o administrador.

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

CÓDIGO DE ERRO DO DLT: INGESTION_GATEWAY_INTERNAL_ERROR

Verifique o(s) arquivo(s) de stdout nos logs de driver.

Conflito de nomenclatura da tabela de origem

Ingestion pipeline error: "org.apache.spark.sql.catalyst.ExtendedAnalysisException: Cannot have multiple queries named `XYZ_snapshot_load` for `XYZ`. 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 nomes devido a várias tabelas de origem nomeadas XYZ em esquemas de origem diferentes que estão sendo ingeridas pelo mesmo pipeline de ingestão para o mesmo esquema de destino.

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

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ÇÃO DE ESQUEMA NÃO INCREMENTAL

NON_INCREMENTAL_SCHEMA_CHANGE: Column '<column>' was added to table '<table>'. A full refresh is required to continue incremental ingestion.

Esse erro ocorre quando uma nova coluna é adicionada a uma tabela de origem enquanto a ingestão incremental está ativa. O conector não pode preencher valores na nova coluna com base nos dados históricos de alterações, portanto é necessária uma atualização completa.

Execute uma atualização completa da tabela afetada para retomar a ingestão. Consulte Atualizar totalmente as tabelas de destino.

MISSING_TABLE_IN_SOURCE

MISSING_TABLE_IN_SOURCE: Table '<schema>.<table>' could not be found in the source database.

Esse erro ocorre quando uma tabela que estava disponível anteriormente no banco de dados de origem não pode mais ser encontrada. As causas mais comuns incluem:

• A tabela foi renomeada ou descartada na origem.
• A tabela está temporariamente indisponível, por exemplo, durante uma janela de manutenção.

Para resolvê-lo:

• Se a tabela estiver temporariamente indisponível, aguarde a conclusão da manutenção e tente executar o pipeline novamente.
• Se a tabela foi renomeada ou recriada, execute uma atualização completa da tabela afetada.
• Se a tabela foi descartada intencionalmente, remova-a do pipeline.

Erros HTTP 403 acessando o armazenamento Azure

Se seu pipeline falhar com um erro como INTERNAL_ERROR: Server returned HTTP response code: 403 for URL, seu cálculo pode não ter acesso ao endpoint de armazenamento do Azure usado pelo conector do SQL Server.

Execute os seguintes testes em um notebook do Azure Databricks para isolar o problema. Use dbutils.secrets para recuperar seu token de assinatura de acesso compartilhado (SAS) em vez de codificá-lo diretamente no código.

Acesso de teste ao endpoint DFS (ADLS Gen2)

O trecho de código a seguir lista, lê e grava no endpoint do Azure Data Lake Storage (ADLS) Gen2, também conhecido como endpoint do Distributed File System (DFS). Substitua os valores provisórios pelos detalhes da sua conta de armazenamento, contêiner e segredo, depois execute para confirmar se o token SAS pode alcançar o endpoint DFS:

storage_account = "<storage-account>"
container = "<container>"
sas_token = dbutils.secrets.get(scope="<scope>", key="<key>")

spark.conf.set(
    f"fs.azure.sas.{container}.{storage_account}.dfs.core.windows.net",
    sas_token
)

base_path = f"abfss://{container}@{storage_account}.dfs.core.windows.net/"

# List contents
display(dbutils.fs.ls(base_path))

# Read a file
df = spark.read.format("parquet").load(base_path + "<path-to-file>")
display(df.limit(10))

# Write a test file
df.write.format("delta").save(base_path + "_connectivity_test")

Testar o acesso ao ponto de extremidade do blob

Se o teste de DFS for bem-sucedido, mas seu pipeline ainda continuar falhando, talvez o conector esteja usando o ponto de extremidade do blob. O snippet a seguir executa as mesmas verificações de listagem, leitura e gravação no ponto de extremidade de blob:

storage_account = "<storage-account>"
container = "<container>"
sas_token = dbutils.secrets.get(scope="<scope>", key="<key>")

spark.conf.set(
    f"fs.azure.sas.{container}.{storage_account}.blob.core.windows.net",
    sas_token
)

base_path = f"wasbs://{container}@{storage_account}.blob.core.windows.net/"

# List files
display(dbutils.fs.ls(base_path))

# Read a file
df = spark.read.format("parquet").load(base_path + "<path-to-file>")
display(df.limit(10))

# Write a test file
df.write.format("delta").save(base_path + "_connectivity_test")

Se algum dos testes retornar um erro 403, o token SAS não possui as permissões necessárias ou não cobre o endpoint correto. Verifique se o token SAS concede pelo menos permissões de Leitura e Lista no container, e o regenere se necessário.

Erros de certificado do servidor TLS

Para solucionar problemas de erros de validação de certificado do servidor TLS, consulte Solucionar problemas de erros de certificado TLS.