Skriptreferenz für SQL Server-Hilfsobjekte

Access-Referenzmaterial für das Skript für SQL Server-Hilfsobjekte, einschließlich Komponenten, Parametern und Problembehandlung.

Überblick

Das Skript installiert gespeicherte Prozeduren und Funktionen des versionsierten Hilfsprogramms, um Ihre SQL Server-Datenbank für die Aufnahme in Lakeflow Connect einzurichten. Zu den Setup-Aufgaben gehören:

• Berechtigungsverwaltung
• Setup der Änderungsnachverfolgung (CT)
• Ändern der Datenerfassungseinrichtung (CDC)
• Plattformerkennung
• DDL unterstützt die Objekterstellung für die Schemaänderungsnachverfolgung

Versionsinformationen

• Aktuelle Version: 1.7
• Hauptversion: 1
• Nebenfassung: 7
• Version-Funktion: lakeflowUtilityVersion()

Was ist neu in Version 1.7

Highlights

• Behebt einen Datenverlust-Fehler in der Schema-Entwicklung. In früheren Versionen konnte das Hinzufügen einer Spalte zu einer Tabelle, die ebenfalls eine bereits vorhandene (nicht-Lakeflow-) Capture-Instanz enthält, die neue Spalte als Eingabe verwenden NULL. Dies wurde behoben, ebenso wie mehrere verwandte Schema-Entwicklungsfehler (siehe Fehlerbehebungen).
• DDL-Unterstützungsobjekte sind jetzt optional für die Änderungsverfolgung. Die DDL-Audittabelle und der Trigger sind für die automatische Schemaentwicklung nicht mehr erforderlich und standardmäßig deaktiviert. Setze sie nur dann ein, @CreateDdlSupportingObjects = 1lakeflowSetupChangeTracking wenn du sie noch willst.
• Zuverlässigere Schema-Entwicklung. Constraint-Änderungen werden so klassifiziert, dass nicht brechende Änderungen wie Fremdschlüssel keine unnötigen vollständigen Aktualisierungen mehr auslösen.

Fehlerkorrekturen

• Mehrere ADD COLUMN Schema-Entwicklungsfehler behoben, darunter Tabellen, die dynamische Datenmaskierung, groß- und schreibungssensitive oder binäre Kollationen sowie eine Reinitialisierungsschleife oder unterbrochene Aufnahme verwenden, wenn eine bereits vorhandene Capture-Instanz vorhanden ist.
• Kollations-Konfliktfehler bei Datenbanken mit einer nicht-standardmäßigen Server-Kollierung wurden behoben.
• DDL-Trigger wurden behoben, die beim Ausführen aus einer Sitzung mit Nicht-Standardoptionen SET ausfallen konnten.
• Behoben lakeflowFixPermissions , um die erforderlichen serverbezogenen Berechtigungen aus der Master-Datenbank zu gewähren.
• Habe die Deinstallation (CLEANUP Modus) behoben, sodass verwaiste DDL-Trigger wurden, die blockieren ALTER TABLEkonnten.

Weitere Änderungen

• Hinzugefügt @AllowDisablePreExistingCaptureInstanceslakeflowSetupChangeDataCapture. Stelle es so ein 1 , dass Lakeflow Connect die bereits vorhandene (nicht Lakeflow-)CDC-Capture-Instanz einer Tabelle übernimmt und verwaltet, anstatt sie dort zu lassen.

Wichtige Komponenten

Funktionen

lakeflowDetectPlatform()

Erkennt den SQL Server-Plattformtyp.

Gibt zurück: 'AZURE_SQL_DATABASE', 'AZURE_SQL_MANAGED_INSTANCE', 'AMAZON_RDS', 'ON_PREMISES' oder 'UNKNOWN'

lakeflowUtilityVersion()

Erkennt die Version der Dienstobjekte.

Rückgabewert: '1.7'

Gespeicherte Prozeduren

lakeflowFixPermissions

Erteilt Benutzern erforderliche Berechtigungen für Datenaufnahmevorgänge.

Parameters:

@Tables Parameteroptionen:

Funktionsweise:

• Berechtigungen SELECT für erforderliche Systemansichten (sys.objects, sys.tables, sys.columns, usw.)
• Finanzhilfen für gespeicherte Systemprozeduren EXECUTE (sp_tables, sp_columns_100usw.)
• Optional kann SELECT auf Benutzertabellen basierend auf dem Parameter @Tables gewährt werden
• Behandelt plattformspezifische Unterschiede (Azure SQL-Datenbank, verwaltete Instanz, RDS, lokal)

lakeflowSetupChangeTracking

Ermöglicht die Änderungsverfolgung auf Datenbank- und Tabellenebene mit optionaler DDL-Unterstützung (opt-in).

Parameters:

@Tables Parameteroptionen:

Funktionsweise:

• Aktiviert die Änderungsnachverfolgung auf Datenbankebene, wenn sie noch nicht aktiviert ist.
• Wenn @CreateDdlSupportingObjects = 1, erzeugt eine versionierte DDL-Audittabelle (lakeflowDdlAudit_1_7) und einen Trigger zur Erfassung von Schemaänderungen
• Aktiviert CT für angegebene Tabellen (überspringt Tabellen ohne Primärschlüssel)
• Erteilt VIEW CHANGE TRACKING berechtigungen für den angegebenen Benutzer
• CLEANUP mode: Entfernt DDL-Supportobjekte

Wichtige Verhaltensweisen:

• Automatisches Überspringen von Tabellen ohne Primärschlüssel (CDC wird für diese empfohlen)
• Intelligente Ermittlung mit dem 'ALL' Parameter
• Idempotent: Sicher, mehrmals auszuführen

lakeflowSetupChangeDataCapture

Aktiviert CDC auf Datenbank- und Tabellenebene mit DDL-Unterstützung und Erfassungsinstanzverwaltung.

Parameters:

@Tables Parameteroptionen:

Funktionsweise:

• Aktiviert CDC auf Datenbankebene, falls noch nicht aktiviert
• Erstellt eine Erfassungsinstanz-Überwachungstabelle (lakeflowCaptureInstanceInfo_1_7)
• Erstellt Hilfsprozeduren für die Aufzeichnungsinstanzverwaltung:
  • lakeflowDisableOldCaptureInstance_1_7
  • lakeflowMergeCaptureInstances_1_7
  • lakeflowRefreshCaptureInstance_1_7
• Erstellt einen Trigger für die ALTER TABLE automatische Behandlung von Schemaänderungen
• Aktiviert CDC für angegebene Tabellen
• Erteilt dem angegebenen Benutzer erforderliche CDC-Berechtigungen.
• CLEANUP modus: Entfernt alle CDC-DDL-Unterstützungsobjekte.

Wichtige Verhaltensweisen:

• Funktioniert mit Tabellen mit oder ohne Primärschlüssel
• Behandelt automatisch die Rotation der Aufzeichnungsinstanz bei Änderungen am Schema.
• Idempotent: Sicher, mehrmals auszuführen

Plattformunterstützung

• Lokaler SQL-Server (EngineEdition 1-4)
• Azure SQL-Datenbank (EngineEdition 5)
• Azure SQL Managed Instance (EngineEdition 8)
• Amazon RDS für SQL Server (vom Servernamenmuster erkannt)

Voraussetzungen

• Der Benutzer, der das Skript ausführt, muss Mitglied der db_owner Rolle sein.
• Für die CT-Einrichtung: Die Änderungsverfolgung muss auf der Plattform verfügbar sein.
• Für das CDC-Setup muss Change Data Capture auf der Plattform verfügbar sein.

Installationsanweisungen

Herunterladen und Ausführen des Skripts

1. Laden Sie die neueste Version des Skripts herunter:

   Utility_script.sql herunterladen

2. Führen Sie das Skript aus:

   1. Öffnen Sie das heruntergeladene Skript in SQL Server Management Studio (SSMS), Azure Data Studio oder Ihrem bevorzugten SQL-Client.
   2. Stellen Sie eine Verbindung mit Ihrer SQL Server-Instanz her.
   3. Vergewissern Sie sich, dass Sie mit der Zieldatenbank verbunden sind, in der Sie die Hilfsprogrammobjekte installieren möchten.
   4. Führen Sie das Skript aus.

3. Installation überprüfen:

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

Alternative: Ausführen mit der Befehlszeile

Wenn Sie sqlcmd verwenden möchten:

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

Beispiel: Beheben von Berechtigungen (nur System)

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

Beispiel: Beheben von Berechtigungen (mit Tabellenzugriff)

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

Beispiele: Einrichtung der Änderungsnachverfolgung

Nur Datenbankebene

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

Aktivieren für alle Tabellen

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

Schemabasiertes Setup

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

Bestimmte Tabellen

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

DDL-Supportobjekte erstellen

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

Beispiele: CDC-Setup

Nur Datenbankebene

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

Aktivieren für alle Tabellen

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

Bestimmte Tabellen

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

Übernehmen Sie die Verantwortung für bereits bestehende Capture-Instanzen

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

Beispiel: Hybrid-Ansatz

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

Beispiel: Bereinigung

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

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

DDL-Unterstützungsobjekte erstellt

Die folgenden DDL-Unterstützungsobjekte werden erstellt, je nachdem, ob Sie die Änderungsnachverfolgung oder CDC verwenden.

Zur Änderungsnachverfolgung

Für CDC

Einschränkungen für die Änderungsnachverfolgung

• Erfordert Primärschlüssel: Tabellen ohne Primärschlüssel können die Änderungsnachverfolgung nicht verwenden.
• Das Skript überspringt Automatisch Tabellen ohne PKs und empfiehlt stattdessen die Verwendung von CDC.

Plattformspezifisches Verhalten

• Azure SQL-Datenbank: Auf gespeicherte Systemprozeduren kann standardmäßig zugegriffen werden (keine EXECUTE Zuschüsse erforderlich).
• Serverbasierte Ansichten: Beschränkter Zugriff in der Azure SQL-Datenbank für Ansichten wie sys.change_tracking_databases.

Upgradepfad

Um aufzurüsten, führe das Skript Utility Objects erneut aus und führe dann die Setup-Prozeduren erneut aus. Das Skript erstellt die Utility-Funktionen neu und entfernt nur alte replicant-präfixierte Objekte aus früheren Versionen. Es lässt deine bestehenden Lakeflow-DDL-Supportobjekte erhalten, sodass der aktuelle DDL-Trigger Schemaänderungen weiterhin erfasst, bis du die Einrichtungsprozeduren erneut ausführen musst. Für Anleitungen siehe Schritt 1: Installieren oder aktualisieren Sie Utility-Objekte.

Was während eines Upgrades geschieht:

• Die vom Skript definierten Utility-Funktionen und Einrichtungsverfahren werden weggelassen und neu erstellt.
• Legacy-präfixierte replicantObjekte aus früheren Versionen werden entfernt.
• Bestehende Lakeflow DDL-Supportobjekte (lakeflowDdlAudit_*, lakeflowDdlAuditTrigger_*, , lakeflowCaptureInstanceInfo_*sowie zugehörige Prozeduren und Trigger) bleiben erhalten. Beim erneuten Ausführen der Einrichtungsprozeduren werden sie in die neue Version übergewandelt. Die Objekte der Capture-Instanz bewegen sich, wann immer Sie erneut ausführen lakeflowSetupChangeDataCapture. Die DDL-Audit-Tabelle und der Trigger verschieben sich nur, wenn Sie mit @CreateDdlSupportingObjects = 1neu ausführenlakeflowSetupChangeTracking, weil sie opt-in sind.
• Änderungsnachverfolgung und CDC bleiben in Ihren Tabellen aktiviert. Das Upgrade deaktiviert sie nicht.
• CDC-Aufnahmeinstanzen sind vom Upgradeskript nicht betroffen.

Nachdem Sie das Upgradeskript ausgeführt haben, führen Sie die Setupprozeduren erneut aus, um DDL-Unterstützungsobjekte für die neue Version neu zu erstellen:

• lakeflowSetupChangeTracking: mit @CreateDdlSupportingObjects = 1, trägt die DDL-Audit-Tabelle und löst den Auslöser auf lakeflowDdlAudit_1_7weiter. Übergebe diese Markierung, wenn deine Installation DDL-Schema-Change Capture verwendet (sie hat eine Tabelle lakeflowDdlAudit ), oder die Objekte bleiben auf der alten Version.
• lakeflowSetupChangeDataCapture: Erstellt und die zugehörigen Prozeduren lakeflowCaptureInstanceInfo_1_7 und Trigger neu.

Beide Prozeduren sind idempotent und sicher, mit den ursprünglichen Setupparametern erneut auszuführen.

Versionsverwaltungsschema: objectName_majorVersion_minorVersion. Aktuelle Objekte verwenden das _1_7 Suffix.

Bewährte Methoden

• Führen Sie immer eine Ausführung als db_owner oder einen Benutzer mit entsprechenden Berechtigungen aus.
• Testen Sie zuerst Nichtproduktionsdatenbanken.
• Verwenden Sie den Hybridansatz für eine umfassende Abdeckung.
• Führen Sie lakeflowFixPermissions nach dem Setup aus, um den ordnungsgemäßen Benutzerzugriff sicherzustellen.
• Berücksichtigen Sie Aufbewahrungszeiträume basierend auf Ihrer Aufnahmehäufigkeit.

Problembehandlung

"Der Benutzer, der dieses Skript ausführt, ist kein Rollenmitglied "db_owner".

Lösung: Als Benutzer mit db_owner Rolle ausführen

"Die Änderungsnachverfolgung ist im Katalog nicht aktiviert"

Lösung: Aktivieren Sie CT auf Datenbankebene oder lassen Sie die Prozedur sie automatisch aktivieren.

"Change Data Capture ist für den Katalog nicht aktiviert"

Lösung: Aktivieren sie CDC auf Datenbankebene, oder lassen Sie die Prozedur automatisch verarbeiten.

"Aufgrund fehlender Primärschlüssel wurden Tabellen übersprungen"

Lösung: Stattdessen für diese Tabellen verwenden lakeflowSetupChangeDataCapture

Validierungsintegration

Die folgenden Hilfsobjekte werden vom Java-Validierungsframework überprüft:

Migrationshinweise

Wenn Sie von älteren Versionen von DDL-Unterstützungsobjekten (vor der Ära der Dienstprogramme) upgraden:

• Das Skript bereinigt automatisch ältere Objekte.
• Es ist keine manuelle Bereinigung erforderlich.
• Version 1.1 konsolidiert alle Funktionen in einheitliche Prozeduren.

Weitere Ressourcen

• SQL Server mithilfe des Dienstprogramm-Objektskripts für die Datenaufnahme vorbereiten
• Konfigurieren von Microsoft SQL Server für die Aufnahme in Azure Databricks
• Microsoft SQL Server-Datenbankbenutzeranforderungen
• Nachverfolgen von Datenänderungen (SQL Server) in der SQL Server-Dokumentation
• Informationen zur Änderungsnachverfolgung (SQL Server) in der SQL Server-Dokumentation
• Was ist Change Data Capture (CDC)? in der SQL Server-Dokumentation