Referencia de scripts de objetos utilitarios de SQL Server

Material de referencia de acceso para el script de objetos de utilidad de SQL Server, incluidos componentes, parámetros y solución de problemas.

Información general

El script instala procedimientos almacenados de utilidad y funciones versionados para configurar tu base de datos de SQL Server para el proceso de ingesta en Lakeflow Connect. Las tareas de instalación incluyen:

• Administración de permisos
• Configurar el seguimiento de cambios (CT)
• Configuración de captura de datos de cambios (CDC)
• Detección de plataformas
• Compatibilidad de DDL con la creación de objetos para el seguimiento de cambios de esquema

Información de versión

• Versión actual: 1.1
• Versión principal: 1
• Versión secundaria: 1
• Función de versión: lakeflowUtilityVersion_1_1()

Componentes claves

Functions

lakeflowDetectPlatform()

Detecta el tipo de plataforma de SQL Server.

Devuelve: 'AZURE_SQL_DATABASE', 'AZURE_SQL_MANAGED_INSTANCE', 'AMAZON_RDS', 'ON_PREMISES'o 'UNKNOWN'

lakeflowUtilityVersion_1_1()

Detecta la versión de objetos de utilidad.

Devuelve: '1.1'

Procedimientos almacenados

lakeflowFixPermissions

Concede permisos necesarios a los usuarios para las operaciones de ingesta.

Parameters:

@Tables opciones de parámetros:

Lo que hace:

• Concesión de permisos SELECT en las vistas del sistema requeridas (sys.objects, sys.tables, sys.columns, etc.)
• Permisos EXECUTE en procedimientos almacenados del sistema (sp_tables, sp_columns_100, etc.)
• Opcionalmente concede permisos en SELECT sobre tablas de usuario basándose en el parámetro @Tables.
• Controla las diferencias específicas de la plataforma (Azure SQL Database, Instancia administrada, RDS, Local)

lakeflowSetupChangeTracking

Habilita el seguimiento de cambios en los niveles de base de datos y tablas con compatibilidad con DDL.

Parameters:

@Tables opciones de parámetros:

Lo que hace:

• Habilita el seguimiento de cambios en el nivel de base de datos si aún no está habilitado
• Crea una tabla de auditoría DDL versionada (lakeflowDdlAudit_1_2)
• Crea un desencadenador de auditoría DDL para capturar los cambios de esquema
• Habilita CT en tablas especificadas (omite tablas sin claves principales)
• Concede VIEW CHANGE TRACKING permisos al usuario especificado
• CLEANUP mode: quita objetos de soporte de DDL

Comportamientos importantes:

• Omite automáticamente las tablas sin claves principales (se recomienda CDC para estas)
• Detección inteligente con el 'ALL' parámetro
• Idempotente: seguro para ejecutarse varias veces

lakeflowSetupChangeDataCapture

Habilita CDC en los niveles de base de datos y tablas con compatibilidad con DDL y administración de instancias de captura.

Parameters:

@Tables opciones de parámetros:

Lo que hace:

• Habilita CDC en el nivel de base de datos si aún no está habilitado
• Crea una tabla de seguimiento de instancias de captura (lakeflowCaptureInstanceInfo_1_2)
• Crea procedimientos auxiliares para la administración de instancias de captura:
  • lakeflowDisableOldCaptureInstance_1_2
  • lakeflowMergeCaptureInstances_1_2
  • lakeflowRefreshCaptureInstance_1_2
• Crea un ALTER TABLE desencadenador para el control automático de cambios de esquema
• Habilita CDC en tablas especificadas
• Concede permisos CDC necesarios al usuario especificado.
• CLEANUP mode: elimina todos los objetos de soporte de CDC DDL

Comportamientos importantes:

• Funciona con tablas con o sin claves principales
• Controla automáticamente la rotación de instancias de captura en los cambios de esquema.
• Idempotente: seguro para ejecutarse varias veces

Compatibilidad con plataformas

• SQL Server en las instalaciones (EngineEdition 1-4)
• Azure SQL Database (EngineEdition 5)
• Instancia administrada de Azure SQL (EngineEdition 8)
• Amazon RDS para SQL Server (detectado por el patrón de nombre de servidor)

Prerrequisitos

• El usuario que ejecuta el script debe ser miembro del db_owner rol
• Para la configuración de CT: El seguimiento de cambios debe estar disponible en dicha plataforma
• ** Para la configuración de CDC, la captura de cambios de datos debe estar habilitada en la plataforma.

Instrucciones de instalación

Descarga y ejecución del script

1. Descargue el script: utility_script.sql

2. Ejecución del script

   • Abra el script descargado en SQL Server Management Studio (SSMS), Azure Data Studio o su cliente SQL preferido.
   • Conéctese a la instancia de SQL Server.
   • Confirme que está conectado a la base de datos de destino donde desea instalar los objetos de utilidad.
   • Ejecute el script.

3. Comprobación de la instalación

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

Alternativa: Ejecutar con la línea de comandos

Si prefiere usar sqlcmd:

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

Ejemplo: Corrección de permisos (solo sistema)

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

Ejemplo: Corrección de permisos (con acceso a tablas)

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

Ejemplos: Configuración del seguimiento de cambios

Solo a nivel de base de datos

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

Habilitar en todas las tablas

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

Configuración basada en esquemas

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

Tablas específicas

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

Ejemplos: configuración CDC

Solo a nivel de base de datos

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

Habilitar en todas las tablas

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

Tablas específicas

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

Ejemplo: Enfoque híbrido

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

Ejemplo: Limpieza

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

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

Objetos de compatibilidad con DDL creados

Se crean los siguientes objetos de soporte DDL, en función de si utiliza el seguimiento de cambios o CDC.

Para el seguimiento de cambios

Para CDC

Limitaciones del seguimiento de cambios

• Requiere claves principales: las tablas sin claves principales no pueden usar el seguimiento de cambios.
• El script omite automáticamente las tablas sin PKs y recomienda usar CDC como alternativa.

Comportamiento específico de la plataforma

• Azure SQL Database: los procedimientos almacenados del sistema son accesibles de forma predeterminada (sin EXECUTE concesiones necesarias).
• Vistas con ámbito de servidor: acceso limitado en Azure SQL Database para vistas como sys.change_tracking_databases.

Ruta de actualización

• El script quita automáticamente todas las versiones anteriores cuando se ejecuta.
• Esquema de control de versiones: objectName_majorVersion_minorVersion
• Los objetos actuales usan _1_1 sufijo para el seguimiento de versiones.

procedimientos recomendados

• Ejecute siempre como db_owner o un usuario con privilegios equivalentes.
• Pruebe primero en bases de datos que no son de producción.
• Use el enfoque híbrido para una cobertura completa.
• Ejecute lakeflowFixPermissions después de la instalación para garantizar el acceso adecuado al usuario.
• Considere los períodos de retención en función de la frecuencia de ingesta.

Solución de problemas

"El usuario que ejecuta este script no es un miembro de rol "db_owner"

Solución: Ejecutar como usuario con db_owner rol

"El seguimiento de cambios no está habilitado en el catálogo"

Solución: habilite CT en el nivel de base de datos o deje que el procedimiento lo controle automáticamente.

"La captura de datos modificados no está habilitada en el catálogo"

Solución: habilite CDC en el nivel de base de datos o permita que el procedimiento lo controle automáticamente.

"Tablas omitidas debido a la falta de claves principales"

Solución: use lakeflowSetupChangeDataCapture en su lugar para estas tablas.

Integración de validación

El marco de validación de Java valida los siguientes objetos de utilidad:

Notas de migración

Si la actualización desde versiones anteriores de DDL admite objetos (era de objetos anteriores a la utilidad):

• El script limpia automáticamente los objetos heredados.
• No se requiere ninguna limpieza manual.
• La versión 1.1 consolida toda la funcionalidad en procedimientos unificados.

Recursos adicionales

• Preparación de SQL Server para la ingesta mediante el script de objetos de utilidad
• Configuración de Microsoft SQL Server para la ingesta en Azure Databricks
• Requisitos de usuario de base de datos de Microsoft SQL Server
• Seguimiento de los cambios de datos (SQL Server) en la documentación de SQL Server
• Acerca de Change Tracking (SQL Server) en la documentación de SQL Server
• ¿Qué es la captura de datos modificados (CDC)? en la documentación de SQL Server