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

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

Visão geral

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

• Gestão de permissões
• Configuração de rastreio de alterações (CT)
• Alterar configuração de captura de dados (CDC)
• Deteção de plataforma
• Criação de objeto de suporte DDL para rastreamento de alterações de esquema

Informações sobre a versão

• Versão Atual: 1.1
• Versão principal: 1
• Versão Menor: 1
• Função de versão: lakeflowUtilityVersion_1_1()

Componentes-chave

Funções

lakeflowDetectPlatform()

Deteta o tipo de plataforma do SQL Server.

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

lakeflowUtilityVersion_1_1()

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

Devoluções: '1.1'

Procedimentos armazenados

lakeflowFixPermissions

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

Parâmetros:

@Tables Opções de parâmetros:

O que faz:

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

lakeflowSetupChangeTracking

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

Parâmetros:

@Tables Opções de parâmetros:

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 versionada (lakeflowDdlAudit_1_2)
• Cria um gatilho de auditoria DDL para capturar alterações de esquema
• Habilita CT em tabelas especificadas (ignora tabelas sem chaves primárias)
• Concede VIEW CHANGE TRACKING permissões ao usuário especificado
• CLEANUP modo: Remova objetos de suporte DDL

Comportamentos importantes:

• Ignora automaticamente tabelas sem chaves primárias (CDC é recomendado para estes)
• Descoberta inteligente com o 'ALL' parâmetro
• Idempotent: Seguro para correr várias vezes

lakeflowSetupChangeDataCapture

Permite o CDC a nível de base de dados e tabela com suporte a DDL e gestão de instâncias de captura.

Parâmetros:

@Tables Opções de parâmetros:

O que faz:

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

Comportamentos importantes:

• Funciona com tabelas com ou sem chaves primárias
• Lida automaticamente com a rotação da instância de captura em alterações de esquema
• Idempotent: Seguro para correr várias vezes

Suporte da plataforma

• SQL Server local (EngineEdition 1-4)
• Banco de Dados SQL do Azure (EngineEdition 5)
• Instância Gerenciada SQL do Azure (EngineEdition 8)
• Amazon RDS for SQL Server (detetado 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 rastreio de alterações deve estar disponível na plataforma
• Para configurar o CDC: a plataforma deve disponibilizar a captura de alterações de dados.

Instruções de instalação

Baixe e execute o script

1. Faça o download do script: utility_script.sql

2. Executar o script

   • Abra o script baixado no SQL Server Management Studio (SSMS), no Azure Data Studio ou no seu cliente SQL preferido.
   • Conecte-se à sua instância do SQL Server.
   • Confirme se você está conectado ao banco de dados de destino onde deseja instalar os objetos do utilitário.
   • Executa 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 preferir utilizar 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 controle 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';

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

Quadros específicos

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

Exemplos: configuração CDC

Somente no nível do banco de dados

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

Ativar em todas as tabelas

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

Quadros específicos

-- 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 o controle de alterações ou CDC.

Para controlo de alterações

Para o CDC

Limitações de controlo 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 o uso de CDC.

Comportamento específico da plataforma

• Banco de Dados SQL do Azure: os procedimentos armazenados do sistema são acessíveis por padrão (sem EXECUTE necessidade de concessão).
• Visualizações com abrangência de servidor: acesso limitado na Base de Dados SQL do Azure para visualizaçõ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.

Melhores práticas

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

Solução de problemas

"O usuário que executa este script não é um membro da 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: habilite a TC no nível do banco de dados ou deixe que o procedimento a manipule automaticamente

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

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

"Tabelas ignoradas devido à falta de chaves primárias"

Solução: use lakeflowSetupChangeDataCapture para estas tabelas em vez disso

Integração de validação

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

Notas sobre migração

Se atualizar a partir de versões mais antigas de objetos de suporte DDL (era anterior aos objetos utilitários):

• O script limpa automaticamente objetos herdados.
• Nenhuma limpeza manual é necessária.
• A versão 1.1 consolida todas as funcionalidades 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 do usuário do banco de dados Microsoft SQL Server
• Rastrear 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 é captura de dados de mudança (CDC)? na documentação do SQL Server