Referência de scripts de objetos utilitários do SQL Server

Acesse o material de referência para o script de objetos do utilitário do SQL Server, incluindo componentes, parâmetros e solução de problemas.

Visão geral

O script instala procedimentos e funções armazenados do utilitário com versão para configurar o banco de dados do SQL Server para ingestão no Lakeflow Connect. As tarefas de instalação incluem:

• Gerenciamento de permissões
• Configuração do rastreamento de alterações (CT)
• Configuração de captura de dados de alteração (CDC)
• Detecção de plataforma
• DDL dá suporte à criação de objeto para controle de alterações de esquema

Informações da versão

• Versão atual: 1.1
• Versão principal: 1
• Versão secundária: 1
• Função de versão: lakeflowUtilityVersion_1_1()

Principais componentes

Functions

lakeflowDetectPlatform()

Detecta o tipo de plataforma do SQL Server.

Retorna: 'AZURE_SQL_DATABASE', 'AZURE_SQL_MANAGED_INSTANCE', 'AMAZON_RDS', 'ON_PREMISES' ou 'UNKNOWN'

lakeflowUtilityVersion_1_1()

Detecta a versão dos objetos do utilitário.

Retorna: '1.1'

Procedimentos armazenados

lakeflowFixPermissions

Concede permissões necessárias aos usuários para operações de ingestão.

Parâmetros:

@Tables opções de parâmetro:

O que faz:

• Permissões SELECT nas exibições de sistema necessárias (sys.objects, sys.tables, sys.columns, etc.)
• Concede EXECUTE em procedimentos armazenados do sistema (sp_tables, sp_columns_100, etc.)
• Opcionalmente, concede SELECT em tabelas de usuário com base no parâmetro @Tables
• Lida com diferenças específicas da plataforma (Banco de Dados SQL do Azure, Instância Gerenciada, RDS, Local)

lakeflowSetupChangeTracking

Habilita o controle de alterações nos níveis de banco de dados e tabela com suporte de DDL.

Parâmetros:

@Tables opções de parâmetro:

O que faz:

• Habilita o controle de alterações no nível do banco de dados se ainda não estiver habilitado
• Cria uma tabela de auditoria DDL com controle de versão (lakeflowDdlAudit_1_2)
• Cria um gatilho de auditoria DDL para capturar alterações de esquema
• Habilita a CT em tabelas especificadas (ignora tabelas sem chaves primárias)
• Concede permissões VIEW CHANGE TRACKING ao usuário especificado
• CLEANUP modo: remove objetos de suporte do DDL

Comportamentos importantes:

• Ignora automaticamente tabelas sem chaves primárias (CDC é recomendado para elas)
• Descoberta inteligente com o 'ALL' parâmetro
• Idempotente: seguro para ser executado várias vezes

lakeflowSetupChangeDataCapture

Habilita o CDC nos níveis de banco de dados e tabela com suporte a DDL e gestão de instâncias de captura.

Parâmetros:

@Tables opções de parâmetro:

O que faz:

• Habilita o CDC no nível do banco de dados se ainda não estiver habilitado
• Cria uma tabela de rastreamento de instância de captura (lakeflowCaptureInstanceInfo_1_2)
• Cria procedimentos auxiliares para o gerenciamento de instância de captura:
  • lakeflowDisableOldCaptureInstance_1_2
  • lakeflowMergeCaptureInstances_1_2
  • lakeflowRefreshCaptureInstance_1_2
• Cria um ALTER TABLE gatilho para tratamento automático de alterações de esquema
• Habilita o CDC em tabelas especificadas
• Concede permissões CDC necessárias ao usuário especificado
• CLEANUP modo: Remove todos os objetos de suporte de DDL do CDC

Comportamentos importantes:

• Funciona com tabelas com ou sem chaves primárias
• Manipula automaticamente a rotação da instância de captura em alterações de esquema
• Idempotente: seguro para ser executado várias vezes

Suporte da plataforma

• SQL Server local (EngineEdition 1-4)
• Banco de Dados SQL do Azure (EngineEdition 5)
• Instância Gerenciada de SQL do Azure (EngineEdition 8)
• Amazon RDS para SQL Server (detectado pelo padrão de nome do servidor)

Pré-requisitos

• O usuário que executa o script deve ser um membro da db_owner função
• Para configuração de CT: o controle de alterações deve estar disponível na plataforma
• Para a configuração do CDC: a captura de dados de alteração deve estar disponível na plataforma

Instruções de instalação

Baixar e executar o script

1. Baixe o script: utility_script.sql

2. Executar o script

   • Abra o script baixado no SSMS (SQL Server Management Studio), no Azure Data Studio ou no cliente SQL preferido.
   • Conecte-se à instância do SQL Server.
   • Confirme se você está conectado ao banco de dados de destino em que deseja instalar os objetos do utilitário.
   • Executar o script.

3. Verificar a instalação

   -- Verify installation
   SELECT dbo.lakeflowUtilityVersion_1_1() AS UtilityVersion;
   SELECT dbo.lakeflowDetectPlatform() AS Platform;
   

Alternativa: executar usando a linha de comando

Se você preferir usar sqlcmd:

sqlcmd -S YourServerName -d YourDatabase -E -i lakeflow_utility_objects.sql

Exemplo: corrigir permissões (somente sistema)

-- Grant system permissions only
EXEC dbo.lakeflowFixPermissions
    @User = 'myuser';

Exemplo: corrigir permissões (com acesso à tabela)

-- Grant system permissions plus access to all tables
EXEC dbo.lakeflowFixPermissions
    @User = 'myuser',
    @Tables = 'ALL';

-- Grant permissions for specific schemas
EXEC dbo.lakeflowFixPermissions
    @User = 'myuser',
    @Tables = 'SCHEMAS:Sales,HR,Production';

-- Grant permissions for specific tables
EXEC dbo.lakeflowFixPermissions
    @User = 'myuser',
    @Tables = 'Sales.Orders,HR.Employees';

Exemplos: Configuração de rastreamento de alterações

Somente no nível do banco de dados

-- Setup CT infrastructure without enabling on tables
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = NULL,
    @User = 'myuser';

Habilitar em todas as tabelas

-- Enable CT on all user tables with primary keys
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'ALL',
    @User = 'myuser';

Configuração baseada em esquema

-- Enable CT on all tables in specific schemas
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'SCHEMAS:Sales,HR',
    @User = 'myuser',
    @Retention = '3 DAYS';

Tabelas específicas

-- Enable CT on specific tables
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'dbo.Table1,Sales.Orders,HR.Employees',
    @User = 'myuser';

Exemplos: Configuração do CDC

Somente no nível do banco de dados

-- Setup CDC infrastructure without enabling on tables
EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = NULL,
    @User = 'myuser';

Habilitar em todas as tabelas

-- Enable CDC on all user tables
EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = 'ALL',
    @User = 'myuser';

Tabelas específicas

-- Enable CDC on specific tables
EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = 'dbo.Table1,Sales.Orders',
    @User = 'myuser';

Exemplo: abordagem híbrida

-- Step 1: Enable CT on tables with primary keys
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'ALL',
    @User = 'myuser';

-- Step 2: Enable CDC on remaining tables (without primary keys)
EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = 'ALL',
    @User = 'myuser';

Exemplo: Limpeza

-- Remove CT DDL support objects
EXEC dbo.lakeflowSetupChangeTracking
    @Mode = 'CLEANUP';

-- Remove CDC DDL support objects
EXEC dbo.lakeflowSetupChangeDataCapture
    @Mode = 'CLEANUP';

Objetos de suporte DDL criados

Os seguintes objetos de suporte DDL são criados, dependendo se você usa controle de alterações ou CDC.

Para controle de alterações

Para CDC

Limitações de controle de alterações

• Requer chaves primárias: tabelas sem chaves primárias não podem usar o controle de alterações.
• O script ignora automaticamente tabelas sem PKs e recomenda usar CDC.

Comportamento específico da plataforma

• Banco de Dados SQL do Azure: os procedimentos armazenados do sistema são acessíveis por padrão (nenhuma EXECUTE concessão é necessária).
• Exibições com escopo de servidor: acesso limitado no Banco de Dados SQL do Azure para exibições como sys.change_tracking_databases.

Caminho de atualização

• O script descarta automaticamente todas as versões anteriores quando executado.
• Esquema de controle de versão: objectName_majorVersion_minorVersion
• Os objetos atuais usam _1_1 sufixo para controle de versão.

Práticas recomendadas

• Sempre execute como db_owner ou um usuário com privilégios equivalentes.
• Teste primeiro em bancos de dados de não produção.
• Use a abordagem híbrida para cobertura abrangente.
• Execute lakeflowFixPermissions após a instalação para garantir o acesso adequado ao usuário.
• Considere os períodos de retenção com base na frequência de ingestão.

Resolução de problemas

"O usuário que executa esse script não é um membro de função 'db_owner'"

Solução: Executar como um usuário com db_owner função

"O controle de alterações não está habilitado no catálogo"

Solução: habilitar a CT no nível do banco de dados ou permitir que o procedimento o manipule automaticamente

"A captura de dados de alteração não está habilitada no catálogo"

Solução: habilitar o CDC no nível do banco de dados ou permitir que o procedimento o manipule automaticamente

"Tabelas puladas devido à ausência de chaves primárias"

Solução: Use lakeflowSetupChangeDataCapture para essas tabelas em vez disso

Integração de validação

Os seguintes objetos utilitários são validados pela estrutura de validação java:

Notas de migração

Se estiver atualizando de versões mais antigas de objetos de suporte DDL (era de objetos pré-utilitários):

• O script limpa automaticamente objetos herdados.
• Nenhuma limpeza manual é necessária.
• A versão 1.1 consolida toda a funcionalidade em procedimentos unificados.

Recursos adicionais

• Preparar o SQL Server para ingestão usando o script de objetos do utilitário
• Configurar o Microsoft SQL Server para ingestão no Azure Databricks
• Requisitos de usuário do banco de dados do Microsoft SQL Server
• Acompanhar alterações de dados (SQL Server) na documentação do SQL Server
• Sobre o Controle de Alterações (SQL Server) na documentação do SQL Server
• O que é a CDA (captura de dados de alterações)? na documentação do SQL Server