Referência de script de objetos utilitáriosSQL Server

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

Visão geral

O script instala utilitários versionados, procedimentos armazenados e funções 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
• Alterar configuração de envio (CT)
• captura de dados de alterações (CDC) (CDC) setup
• Detecção de plataforma
• Suporte a DDL para criação de objetos para alteração 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()

componentes principais

Funções

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 russos.

Devoluções: '1.1'

Procedimentos armazenados

lakeflowFixPermissions

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

Parâmetros:

Parâmetro	Descrição
@User (NVARCHAR(128))	Obrigatório. Nome de usuário ao qual conceder permissões
@Tables (NVARCHAR(MAX))	Opcional. Controla o escopo de permissões em nível de tabela.

@Tables opções de parâmetros:

Opção	Descrição
NULL	Conceder apenas permissões de nível de sistema (default)
'ALL'	Conceda permissões em todas as tabelas de usuários no banco de dados.
'SCHEMAS:Schema1,Schema2'	Conceder permissões em todas as tabelas nos esquemas especificados.
'Schema.Table1,Schema.Table2'	Conceder permissões em tabelas específicas
Suporte a curingas	Exemplo: 'Sales.*,HR.Employees'

O que faz:

• Concede SELECT na visão de sistema necessária (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ários com base no parâmetro @Tables .
• Lida com diferenças específicas da plataforma (Banco de Dados SQL Azure , instância gerenciada, RDS, local).

lakeflowSetupChangeTracking

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

Parâmetros:

Parâmetro	Descrição
@Tables (NVARCHAR(MAX))	Opcional. Tabelas para habilitar a TC em
@User (NVARCHAR(128))	Opcional. O usuário deverá conceder permissões a
@Retention (NVARCHAR(50))	Opcional. Período de retenção CT (default: '2 DAYS')
@Mode (NVARCHAR(10))	Opcional. 'INSTALL' (default) ou 'CLEANUP'

@Tables opções de parâmetros:

Opção	Descrição
NULL	Configurar suporte apenas para CT e DDL em nível de banco de dados (sem habilitar tabelas).
'ALL'	Habilite o CT em todas as tabelas de usuários com chave primária.
'SCHEMAS:Schema1,Schema2'	Ativar CT em tabelas nos esquemas especificados
'Schema.Table1,Schema.Table2'	Habilitar CT em tabelas específicas
Suporte a curingas	Exemplo: 'Sales.*,HR.Employees'

O que faz:

• Permite alterar o acompanhamento no nível do banco de dados, caso ainda não esteja ativado.
• Cria uma tabela de auditoria DDL versionada (lakeflowDdlAudit_1_2)
• Cria um gatilho de auditoria DDL para capturar alterações de esquema.
• Habilita o CT em tabelas específicas (ignora tabelas sem chave primária).
• Concede permissões VIEW CHANGE TRACKING ao usuário especificado.
• CLEANUP modo: Remove objetos de suporte DDL

Comportamentos importantes:

• Ignora automaticamente tabelas sem chave primária (CDC é recomendado para esses casos).
• Descoberta inteligente com o parâmetro 'ALL'
• Idempotente: Seguro para execução múltiplas vezes

lakeflowSetupChangeDataCapture

Habilita a captura de erros de captura (CDC) nos níveis de banco de dados e tabela, com suporte a DDL e gerenciamento de instâncias de captura.

Parâmetros:

Parâmetro	Descrição
@Tables (NVARCHAR(MAX))	Opcional. Tabelas para habilitar o CDC em
@User (NVARCHAR(128))	Opcional. O usuário deverá conceder permissões a
@Mode (NVARCHAR(10))	Opcional. 'INSTALL' (default) ou 'CLEANUP'

@Tables opções de parâmetros:

Opção	Descrição
NULL	Configure o suporte a CDC e DDL somente no nível do banco de dados.
'ALL'	Ative o CDC em todas as tabelas de usuários.
'SCHEMAS:Schema1,Schema2'	Habilitar CDC em tabelas nos esquemas especificados
'Schema.Table1,Schema.Table2'	Habilitar o CDC em tabelas específicas

O que faz:

• Habilita o CDC no nível do banco de dados, caso ainda não esteja habilitado.

• Cria uma tabela de acompanhamento da 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 específicas.

• Concede as permissões necessárias do CDC ao usuário especificado.

• CLEANUP modo: Remove todos os objetos de suporte DDL do CDC

Comportamentos importantes:

• Funciona com tabelas com ou sem chave primária.
• Gerencia automaticamente a rotação da instância de captura em caso de alterações de esquema.
• Idempotente: Seguro para execução múltiplas vezes

Suporte da plataforma

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

Pré-requisitos

• O usuário que executa o script deve ser membro da função db_owner .
• Para configuração de TC: A opção Alterar acompanhamento deve estar disponível na plataforma.
• Para configuração CDC : a captura de dados de alterações (CDC) deve estar disponível na plataforma

Instruções de instalação

baixe e execute o script

1. Baixe o roteiro

   baixar lakeflow_utility_objects.sql de [URL A SER DETERMINADA]

2. execução do roteiro

   • Abra o script de downloads no SQL Server Management Studio (SSMS), 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 utilitários.
   • execução do roteiro.

3. Verifique a instalação

   SQL

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

Alternativa: execução usando a linha de comando

Se preferir usar sqlcmd:

Bash

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

nota

Substitua YourServerName e YourDatabase pelos nomes reais do seu servidor e banco de dados. Use -U username -P password em vez de -E se não estiver usando autenticação do Windows.

Exemplo: Corrigir permissões (somente do sistema)

SQL

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

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

SQL

-- 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: Alterar configuração de envio

Somente em nível de banco de dados

SQL

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

Ativar em todas as tabelas

SQL

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

Configuração baseada em esquema

SQL

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

Tabelas específicas

SQL

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

Exemplos: Configuração do CDC

Somente em nível de banco de dados

SQL

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

Ativar em todas as tabelas

SQL

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

Tabelas específicas

SQL

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

Exemplo: Abordagem híbrida

SQL

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

SQL

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

Para alterar a reprodução

Tipo de objeto	Nome	Descrição
Tabela	lakeflowDdlAudit_1_2	História de alteração de DDL das lojas
Trigger	lakeflowDdlAuditTrigger_1_2	Captura eventos ALTER TABLE

Para o CDC

Tipo de objeto	Nome	Descrição
Tabela	lakeflowCaptureInstanceInfo_1_2	As faixas capturam instâncias
Procedimento	lakeflowDisableOldCaptureInstance_1_2	Remove a instância de captura antiga
Procedimento	lakeflowMergeCaptureInstances_1_2	mesclar dados entre instâncias
Procedimento	lakeflowRefreshCaptureInstance_1_2	Cria uma nova instância de captura.
Trigger	lakeflowAlterTableTrigger_1_2	Lida com alterações de esquema

Alterar limitações de envio

• Requer chave primária: Tabelas sem chave primária não podem usar acompanhamento de alterações.
• O script ignora automaticamente tabelas sem chaves primárias e recomenda o uso do CDC em vez disso.

Comportamento específico da plataforma

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

Caminho de atualização

• O script descarta automaticamente todas as versões anteriores ao ser executado.
• Esquema de versionamento: objectName_majorVersion_minorVersion
• Os objetos atuais utilizam o sufixo _1_1 para acompanhamento de versão.

Melhores práticas

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

Solução de problemas

"O usuário que executa este script não é membro da função 'db_owner'"

soluções : Execute como um usuário com função db_owner

"Alterar conforme necessário não está habilitado no catálogo"

Soluções : Habilite o CT no nível do banco de dados ou deixe o procedimento lidar com ele automaticamente.

"A captura de dados de alterações (CDC) não está habilitada no catálogo"

Soluções : Habilite CDC no nível do banco de dados ou deixe o procedimento lidar com isso automaticamente.

"Tabelas ignoradas devido à ausência da chave primária"

soluções : 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 :

Objeto	Descrição
SqlServerUtilityObjectsSetupValidator	Valida a instalação de objetos de utilidades
SqlServerChangeDataManagementSetupValidator	Valida a configuração CT/CDC
SqlServerDdlSupportObjectsSetupValidator	Valida objetos de suporte DDL
SqlServerPermissionsSetupValidator	Valida permissões

Notas sobre migração

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

• O script limpa automaticamente os objetos legados.
• Não é necessária limpeza manual.
• A versão 1.1 consolida todas as funcionalidades em procedimentos unificados.

Recursos adicionais

• Prepare SQL Server para ingestão usando o script de objetos utilitários.
• Configure o Microsoft SQL Server para ingestão de dados no 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 a alteração de acompanhamento (SQL Server) na documentação SQL Server
• O que é captura de dados de alterações (CDC) (CDC)? na documentação SQL Server