Scriptreferentie voor SQL Server-hulpprogrammaobjecten

Toegang tot referentiemateriaal voor het script voor hulpprogrammaobjecten van SQL Server, inclusief onderdelen, parameters en probleemoplossing.

Overzicht

Met het script worden geversioneerde hulpprogramma's opgeslagen procedures en functies geïnstalleerd om uw SQL Server-database in te richten voor gegevensopname in Lakeflow Connect. Installatietaken zijn onder andere:

• Machtigingsbeheer
• Instelling voor het bijhouden van wijzigingen (CT)
• CDC-installatie (Data Capture) wijzigen
• Platformdetectie
• DDL-ondersteuning voor het maken van objecten voor het bijhouden van schemawijziging

Versie-informatie

• Huidige versie: 1.7
• Hoofdversie: 1
• Kleine versie: 7
• Versiebeheer: lakeflowUtilityVersion()

Wat is er nieuw in versie 1.7

Hoogtepunten

• Lost een dataverliesbug op in schema-evolutie. In eerdere versies kon het toevoegen van een kolom aan een tabel die ook een vooraf bestaande (niet-Lakeflow) capture-instantie bevat, de nieuwe kolom invoeren als NULL. Dit is opgelost, samen met verschillende gerelateerde schema-evolutiefouten (zie Bugfixes).
• DDL-ondersteuningsobjecten zijn nu optioneel voor wijzigingstracking. De DDL-audittabel en trigger zijn niet langer vereist voor automatische schema-evolutie en staan standaard uit. Stel het alleen in @CreateDdlSupportingObjects = 1 als lakeflowSetupChangeTracking je ze nog wilt.
• Meer betrouwbare schema-evolutie. Beperkingswijzigingen worden zo geclassificeerd dat niet-brekende wijzigingen, zoals vreemde sleutels, niet langer onnodige volledige verversingen veroorzaken.

Correcties

• Verschillende schema-evolutiefouten opgelost ADD COLUMN , waaronder tabellen die dynamische datamaskering gebruiken, hoofdlettergevoelige of binaire collaties, en een herinitialisatielus of onderbroken invoering wanneer een bestaande capture-instantie aanwezig is.
• Correcties voor collatie-conflicten op databases met een niet-standaard server-collatie.
• DDL-triggers opgelost die konden falen als ze vanuit een sessie met niet-standaard SET opties werden uitgevoerd.
• Aangepast lakeflowFixPermissions om de vereiste server-scoped rechten van de masterdatabase te verlenen.
• Opgelost met het verwijderen (CLEANUP modus) waardoor verweesde DDL-triggers achterbleven die konden blokkeren ALTER TABLE.

Andere wijzigingen

• Toegevoegd@AllowDisablePreExistingCaptureInstances.lakeflowSetupChangeDataCapture Stel het zo in dat 1 Lakeflow Connect de reeds bestaande (niet-Lakeflow) CDC-capture-instantie van een tabel overneemt en beheert in plaats van deze te laten staan.

Belangrijkste onderdelen

Functions

lakeflowDetectPlatform()

Hiermee wordt het sql Server-platformtype gedetecteerd.

Retourneert: 'AZURE_SQL_DATABASE', 'AZURE_SQL_MANAGED_INSTANCE', 'AMAZON_RDS', , of 'ON_PREMISES''UNKNOWN'

lakeflowUtilityVersion()

Hiermee wordt de versie van de hulpprogrammaobjecten gedetecteerd.

Retourneert: '1.7'

Opgeslagen procedures

lakeflowFixPermissions

Verleent vereiste machtigingen aan gebruikers voor opnamebewerkingen.

Parameters:

@Tables parameteropties:

Wat het doet:

• Subsidies SELECT voor vereiste systeemweergaven (sys.objects, sys.tables, sys.columnsenzovoort)
• Subsidies EXECUTE voor door het systeem opgeslagen procedures (sp_tables, sp_columns_100enz.)
• Verleent SELECT aan gebruikerstabellen op basis van de @Tables parameter, optioneel
• Behandelt platformspecifieke verschillen (Azure SQL Database, Managed Instance, RDS, On-premises)

lakeflowSetupChangeTracking

Maakt wijzigingstracking mogelijk op database- en tabelniveau, met optionele DDL-ondersteuning (opt-in).

Parameters:

@Tables parameteropties:

Wat het doet:

• Hiermee schakelt u, indien nog niet ingeschakeld, het bijhouden van wijzigingen op databaseniveau in.
• Wanneer @CreateDdlSupportingObjects = 1, creëert een versiegewijze DDL-audittabel (lakeflowDdlAudit_1_7) en een trigger om schemawijzigingen vast te leggen
• Hiermee schakelt u CT in voor opgegeven tabellen (slaat tabellen zonder primaire sleutels over)
• Verleent VIEW CHANGE TRACKING machtigingen aan de opgegeven gebruiker
• CLEANUP modus: DDL-ondersteuningsobjecten verwijderen

Belangrijk gedrag:

• Hiermee worden tabellen zonder primaire sleutels automatisch overgeslagen (CDC wordt hiervoor aanbevolen)
• Slimme detectie met de 'ALL' parameter
• Idempotent: Veilig om meerdere keren te worden uitgevoerd

lakeflowSetupChangeDataCapture

CDC wordt ingeschakeld op database- en tabelniveau, met DDL-ondersteuning en beheer van capture-instanties.

Parameters:

@Tables parameteropties:

Wat het doet:

• Schakelt CDC in op databaseniveau als deze nog niet is ingeschakeld
• Maakt een traceringstabel voor een vastleg-instantie (lakeflowCaptureInstanceInfo_1_7)
• Hiermee worden helperprocedures gemaakt voor beheer van vastleginstantie:
  • lakeflowDisableOldCaptureInstance_1_7
  • lakeflowMergeCaptureInstances_1_7
  • lakeflowRefreshCaptureInstance_1_7
• Hiermee maakt u een ALTER TABLE trigger voor automatische verwerking van schemawijziging
• Schakelt CDC in op opgegeven tabellen
• Verleent vereiste CDC-machtigingen aan de opgegeven gebruiker
• CLEANUP modus: Verwijdert alle CDC DDL-ondersteuningsobjecten

Belangrijk gedrag:

• Werkt met tabellen met of zonder primaire sleutels
• Automatisch de rotatie van vastleginstantie afhandelen bij schemawijzigingen
• Idempotent: Veilig om meerdere keren te worden uitgevoerd

Platformondersteuning

• Lokaal geïnstalleerde SQL Server (EngineEdition 1-4)
• Azure SQL Database (EngineEdition 5)
• Azure SQL Managed Instance (EngineEdition 8)
• Amazon RDS voor SQL Server (gedetecteerd door servernaampatroon)

Vereiste voorwaarden

• Gebruiker die het script uitvoert, moet lid zijn van db_owner de rol
• Voor CT-installatie: Wijzigingen bijhouden moet beschikbaar zijn op het platform
• Voor CDC-installatie: Change data capture moet beschikbaar zijn op het platform

Installatie-instructies

Het script downloaden en uitvoeren

1. Download de nieuwste versie van het script:

   Utility_script.sql downloaden

2. Voer het script uit:

   1. Open het gedownloade script in SQL Server Management Studio (SSMS), Azure Data Studio of uw favoriete SQL-client.
   2. Maak verbinding met uw SQL Server-exemplaar.
   3. Controleer of u bent verbonden met de doeldatabase waar u de hulpprogrammaobjecten wilt installeren.
   4. Voer het script uit.

3. Installatie controleren:

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

Alternatief: Uitvoeren met behulp van de opdrachtregel

Als u liever sqlcmd gebruikt:

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

Voorbeeld: Machtigingen herstellen (alleen systeem)

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

Voorbeeld: Machtigingen herstellen (met tabeltoegang)

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

Voorbeelden: Instelling voor het bijhouden van wijzigingen

Alleen op databaseniveau

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

Inschakelen voor alle tabellen

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

Installatie op basis van schema

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

Specifieke tabellen

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

Maak DDL-ondersteuningsobjecten aan

-- Enable CT and create the DDL audit table and trigger for schema-change capture
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'ALL',
    @User = 'myuser',
    @CreateDdlSupportingObjects = 1;

Voorbeelden: CDC-installatie

Alleen op databaseniveau

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

Inschakelen voor alle tabellen

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

Specifieke tabellen

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

Neem eigenaar van bestaande capture-instanties

-- Allow Lakeflow to disable pre-existing (non-Lakeflow) capture instances
-- during schema change handling
EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = 'ALL',
    @User = 'myuser',
    @AllowDisablePreExistingCaptureInstances = 1;

Voorbeeld: Hybride benadering

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

Voorbeeld: Opschonen

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

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

DDL-ondersteuningsobjecten gemaakt

De volgende DDL-ondersteuningsobjecten worden gemaakt, afhankelijk van of u wijzigingen bijhouden of CDC gebruikt.

Voor het bijhouden van wijzigingen

Voor CDC

Beperkingen voor het bijhouden van wijzigingen

• Primaire sleutels vereist: tabellen zonder primaire sleutels kunnen geen wijzigingen bijhouden gebruiken.
• Het script slaat automatisch tabellen zonder PK's over en raadt aan om in plaats daarvan CDC te gebruiken.

Platformspecifiek gedrag

• Azure SQL Database: door het systeem opgeslagen procedures zijn standaard toegankelijk (geen EXECUTE subsidies nodig).
• Server-brede weergaven: Beperkte toegang in Azure SQL Database voor weergaven zoals sys.change_tracking_databases.

Upgradepad

Om te upgraden, voer je het utility objects-script opnieuw uit en voer je vervolgens de setupprocedures opnieuw uit. Het script recreëert de hulpfuncties en verwijdert alleen legacy replicant-prefix-objecten uit eerdere releases. Het laat je bestaande Lakeflow DDL-ondersteuningsobjecten intact, zodat de huidige DDL-trigger schemawijzigingen blijft vastleggen totdat je de setupprocedures opnieuw uitvoert. Voor instructies, zie Stap 1: Installeer of upgrade hulpobjecten.

Wat gebeurt er tijdens een upgrade:

• De hulpfuncties en installatieprocedures die door het script zijn gedefinieerd, worden verwijderd en opnieuw aangemaakt.
• Legacy replicant-prefix objecten uit eerdere releases worden verwijderd.
• Bestaande Lakeflow DDL-ondersteuningsobjecten (lakeflowDdlAudit_*, lakeflowDdlAuditTrigger_*, , lakeflowCaptureInstanceInfo_*en gerelateerde procedures en triggers) blijven aanwezig. Door de installatieprocedures opnieuw uit te voeren, worden ze overgezet naar de nieuwe versie. De objecten van de capture instance bewegen telkens wanneer je opnieuw uitvoert lakeflowSetupChangeDataCapture. De DDL-audittabel en trigger verplaatsen alleen wanneer je opnieuw start lakeflowSetupChangeTracking met @CreateDdlSupportingObjects = 1, omdat ze opt-in zijn.
• Wijzigingen bijhouden en CDC blijven ingeschakeld voor uw tabellen. De upgrade schakelt ze niet uit.
• CDC-capture-exemplaren worden niet beïnvloed door het upgradescript.

Nadat u het upgradescript hebt uitgevoerd, voert u de installatieprocedures opnieuw uit om DDL-ondersteuningsobjecten voor de nieuwe versie opnieuw te maken:

• lakeflowSetupChangeTracking: met @CreateDdlSupportingObjects = 1, draagt de DDL-audittabel en triggert door naar lakeflowDdlAudit_1_7. Sla deze vlag door als je installatie DDL schema-change capture gebruikt (het heeft een lakeflowDdlAudit tabel), of de objecten blijven op de oude versie.
• lakeflowSetupChangeDataCapture: Maakt opnieuw lakeflowCaptureInstanceInfo_1_7 en de bijbehorende procedures en trigger.

Beide procedures zijn idempotent en veilig om opnieuw uit te voeren met de oorspronkelijke installatieparameters.

Versiebeheerschema: objectName_majorVersion_minorVersion. Huidige objecten gebruiken het _1_7 achtervoegsel.

Beste praktijken

• Voer altijd uit als db_owner of een gebruiker met gelijkwaardige bevoegdheden.
• Test eerst op databases buiten productie.
• Gebruik de hybride benadering voor uitgebreide dekking.
• Voer lakeflowFixPermissions na de installatie uit om de juiste gebruikerstoegang te garanderen.
• Houd rekening met bewaarperioden op basis van uw opnamefrequentie.

Probleemoplossingsproces

'Gebruiker die dit script uitvoert, is geen lid van de rol 'db_owner'

Oplossing: Uitvoeren als gebruiker met db_owner rol

"Wijzigingen bijhouden is niet ingeschakeld voor catalogus"

Oplossing: SCHAKEL CT in op databaseniveau of laat de procedure automatisch afhandelen

"Het vastleggen van gegevens wijzigen is niet ingeschakeld in de catalogus"

Oplossing: Schakel CDC in op databaseniveau of laat de procedure het automatisch afhandelen

"Tabellen overgeslagen vanwege ontbrekende primaire sleutels"

Oplossing: Gebruik lakeflowSetupChangeDataCapture in plaats daarvan voor deze tabellen

Validatie-integratie

De volgende hulpprogrammaobjecten worden gevalideerd door het Java-validatieframework:

Migratienotities

Als u een upgrade uitvoert van oudere versies van DDL-ondersteuningsobjecten (tijdperk van pre-utility-objecten):

• Met het script worden verouderde objecten automatisch opgeschoond.
• Handmatig opschonen is niet vereist.
• Versie 1.1 consolideert alle functionaliteit in geïntegreerde procedures.

Aanvullende bronnen

• SQL Server voorbereiden voor opname met behulp van het script voor hulpprogrammaobjecten
• Microsoft SQL Server configureren voor opname in Azure Databricks
• Gebruikersvereisten voor Microsoft SQL Server-database
• Gegevenswijzigingen bijhouden (SQL Server) in de SQL Server-documentatie
• Over Wijzigingen bijhouden (SQL Server) in de SQL Server-documentatie
• Wat is gegevensvastlegging bij wijzigingen (CDC)? in de SQL Server-documentatie