Dokumentacja skryptu obiektów narzędziowych programu SQL Server

Dostęp do materiałów referencyjnych dla skryptu obiektów narzędzi programu SQL Server, w tym składników, parametrów i rozwiązywania problemów.

Przegląd

Skrypt instaluje wersjonowane procedury składowane i funkcje narzędziowe, aby skonfigurować bazę danych SQL Server na potrzeby pozyskiwania danych w Lakeflow Connect. Zadania konfiguracji obejmują:

  • Zarządzanie uprawnieniami
  • Konfiguracja śledzenia zmian (CT)
  • Zmienianie konfiguracji przechwytywania danych (CDC)
  • Wykrywanie platformy
  • Obsługa tworzenia obiektów WDL na potrzeby śledzenia zmian schematu

Informacje o wersji

  • Aktualna wersja: 1.7
  • Wersja główna: 1
  • Wersja mniejsza: 7
  • Funkcja wersji: lakeflowUtilityVersion()

Co nowego w wersji 1.7

Najważniejsze informacje

  • Naprawia błąd utraty danych w ewolucji schematu. We wcześniejszych wersjach dodanie kolumny do tabeli, która zawiera także istniejącą instancję przechwytu (nie-Lakeflow), mogło przyjąć nową kolumnę jako .NULL Zostało to naprawione, podobnie jak kilka powiązanych błędów ewolucji schematu (patrz Poprawki błędów).
  • Obiekty wsparcia DDL są teraz opcjonalne do śledzenia zmian. Tabela audytowa DDL i wyzwalacz nie są już potrzebne do automatycznej ewolucji schematu i są domyślnie wyłączone. Wybierz @CreateDdlSupportingObjects = 1lakeflowSetupChangeTracking tylko jeśli nadal je chcesz.
  • Bardziej wiarygodna ewolucja schematów. Zmiany ograniczeń są klasyfikowane tak, aby te nieprzełamujące, takie jak klucze obce, nie wywoływały już niepotrzebnych pełnych odświeżeń.

Poprawki błędów

  • Naprawiono kilka ADD COLUMN błędów ewolucji schematu, w tym tabele wykorzystujące dynamiczne maskowanie danych, sortowanie wielkości liter lub binarne oraz pętlę reinicjalizacji lub przerwane pobieranie, gdy obecna jest wcześniej instancja przechwytu.
  • Naprawiono błędy konfliktu kolacji w bazach danych z niestandardową kolidacją serwera.
  • Naprawiono wyzwalacze DDL, które mogły się nie udać podczas uruchamiania z sesji z opcjami niedomyślnymi SET .
  • Naprawiono, lakeflowFixPermissions aby przyznać wymagane uprawnienia ograniczone do serwera z bazy głównej.
  • Naprawiono tryb odinstalowywaniaCLEANUP , pozostawiając osierocone wyzwalacze DDL, które mogły blokować ALTER TABLE.

Inne zmiany

  • Dodano @AllowDisablePreExistingCaptureInstances .lakeflowSetupChangeDataCapture Ustaw tak, aby 1 Lakeflow Connect przejął i zarządzał istniejącą (nie-Lakeflow) instancją CDC capture w tabeli, zamiast zostawiać ją na miejscu.

Najważniejsze składniki

Functions

lakeflowDetectPlatform()

Wykrywa typ platformy programu SQL Server.

Zwraca: 'AZURE_SQL_DATABASE', 'AZURE_SQL_MANAGED_INSTANCE', 'AMAZON_RDS', 'ON_PREMISES', lub 'UNKNOWN'

lakeflowUtilityVersion()

Wykrywa wersję obiektów narzędziowych.

Zwroty: '1.7'

Procedury przechowywane

lakeflowFixPermissions

Przyznaje użytkownikom wymagane uprawnienia do operacji pozyskiwania.

Parametry:

Parameter Description
@User (NVARCHAR(128)) To jest wymagane. Nazwa użytkownika, któremu należy udzielić uprawnień
@Tables (NVARCHAR(MAX)) Opcjonalny. Steruje zakresem uprawnień na poziomie tabeli

@Tables opcje parametrów:

Option Description
NULL Przyznawanie tylko uprawnień na poziomie systemu (ustawienie domyślne)
'ALL' Udzielanie uprawnień do wszystkich tabel użytkowników w bazie danych
'SCHEMAS:Schema1,Schema2' Udzielanie uprawnień do wszystkich tabel w określonych schematach
'Schema.Table1,Schema.Table2' Udzielanie uprawnień do określonych tabel
Obsługa symboli wieloznacznych Przykład: 'Sales.*,HR.Employees'

Co to robi:

  • Przyznaje SELECT uprawnienia do wymaganych widoków systemowych (sys.objects, sys.tables, sys.columns, itd.)
  • Dotacje EXECUTE na systemowe procedury składowane (sp_tables, sp_columns_100itp.)
  • Opcjonalnie przyznaje SELECT dla tabel użytkownika na podstawie parametru @Tables
  • Obsługuje różnice specyficzne dla platformy (Azure SQL Database, Wystąpienie zarządzane, RDS, lokalnie)

lakeflowSetupChangeTracking

Umożliwia śledzenie zmian na poziomie bazy danych i tabel, z opcjonalnym wsparciem DDL (opt-in).

Parametry:

Parameter Description
@Tables (NVARCHAR(MAX)) Opcjonalny. Tabele umożliwiające włączenie funkcji CT
@User (NVARCHAR(128)) Opcjonalny. Użytkownik musi udzielić uprawnień
@Retention (NVARCHAR(50)) Opcjonalny. Okres przechowywania CT (wartość domyślna: '2 DAYS')
@Mode (NVARCHAR(10)) Opcjonalny. 'INSTALL' (wartość domyślna) lub 'CLEANUP'
@CreateDdlSupportingObjects (BIT) Opcjonalny. Wartość domyślna 0. Ustaw tak, 1 aby utworzyć tabelę audytową DDL i wyzwalać śledzenie zmian schematu (DDL). Weryfikacja konfiguracji zakłada, że ta wartość będzie odpowiadać konfiguracji twojego pipeline'u. Jeśli wartości się nie zgadzają, walidacja konfiguracji zgłasza niepowodzenie.

@Tables opcje parametrów:

Option Description
NULL Skonfiguruj tylko CT na poziomie bazy danych, bez włączenia tabel (tworzy też obiekty wsparcia DDL, gdy @CreateDdlSupportingObjects = 1)
'ALL' Włącz CT we wszystkich tabelach użytkowników z kluczami podstawowymi
'SCHEMAS:Schema1,Schema2' Włącz funkcję CT w tabelach w zdefiniowanych schematach
'Schema.Table1,Schema.Table2' Włączanie funkcji CT w określonych tabelach
Obsługa symboli wieloznacznych Przykład: 'Sales.*,HR.Employees'

Co to robi:

  • Włącza śledzenie zmian na poziomie bazy danych, jeśli nie jest jeszcze włączone
  • Gdy @CreateDdlSupportingObjects = 1, tworzy wersjonowaną tabelę audytową DDL (lakeflowDdlAudit_1_7) oraz wyzwalacz do rejestrowania zmian schematu
  • Włącza funkcję CT w określonych tabelach (pomija tabele bez kluczy podstawowych)
  • Przyznaje VIEW CHANGE TRACKING uprawnienia określonemu użytkownikowi
  • CLEANUP tryb: Usuwa obiekty obsługi DDL

Ważne zachowania:

  • Automatycznie pomija tabele bez kluczy podstawowych (zalecane jest użycie usługi CDC)
  • Inteligentne odnajdywanie za pomocą parametru 'ALL'
  • Idempotentne: Bezpieczne uruchamianie wiele razy

lakeflowSetupChangeDataCapture

Włącza usługę CDC na poziomach bazy danych i tabel z obsługą języka DDL i zarządzaniem wystąpieniami przechwytywania.

Parametry:

Parameter Description
@Tables (NVARCHAR(MAX)) Opcjonalny. Tabele umożliwiające włączenie usługi CDC na
@User (NVARCHAR(128)) Opcjonalny. Użytkownik musi udzielić uprawnień
@Mode (NVARCHAR(10)) Opcjonalny. 'INSTALL' (wartość domyślna) lub 'CLEANUP'
@AllowDisablePreExistingCaptureInstances (BIT) Opcjonalny. 0 (domyślne) pozostawia istniejące, nie-Lakeflow instancje przechwytywania nietknięte podczas obsługi zmian schematu. Ustaw tak, 1 aby Lakeflow Connect przejął własność i wyłączył istniejące instancje przechwytu.

@Tables opcje parametrów:

Option Description
NULL Konfigurowanie tylko usługi CDC i DDL na poziomie bazy danych
'ALL' Włączanie usługi CDC we wszystkich tabelach użytkowników
'SCHEMAS:Schema1,Schema2' Włącz CDC w tabelach w określonych schematach
'Schema.Table1,Schema.Table2' Włączanie usługi CDC dla określonych tabel

Co to robi:

  • Włącza usługę CDC na poziomie bazy danych, jeśli nie została jeszcze włączona
  • Tworzy tabelę śledzenia instancji przechwytywania (lakeflowCaptureInstanceInfo_1_7)
  • Tworzy procedury pomocnicze do zarządzania wystąpieniami przechwytywania:
    • lakeflowDisableOldCaptureInstance_1_7
    • lakeflowMergeCaptureInstances_1_7
    • lakeflowRefreshCaptureInstance_1_7
  • Tworzy ALTER TABLE wyzwalacz do automatycznej obsługi zmian schematu
  • Włącza usługę CDC w określonych tabelach
  • Przyznaje wymagane uprawnienia CDC do określonego użytkownika
  • CLEANUP Tryb: Usuwa wszystkie objekty wspierające DDL CDC

Ważne zachowania:

  • Działa z tabelami, które mają klucze podstawowe lub ich nie mają
  • Automatycznie zarządza rotacją instancji przechwytywania w przypadku zmian schematu
  • Idempotentne: Bezpieczne uruchamianie wiele razy

Wsparcie platform

  • Lokalny program SQL Server (engineEdition 1-4)
  • Azure SQL Database (engineEdition 5)
  • Azure SQL Managed Instance (EngineEdition 8)
  • Usługa Amazon RDS dla programu SQL Server (wykryta przez wzorzec nazwy serwera)

Wymagania wstępne

  • Użytkownik wykonujący skrypt musi być członkiem db_owner roli
  • W przypadku konfiguracji CT: śledzenie zmian musi być dostępne na platformie
  • W przypadku konfiguracji usługi CDC: przechwytywanie zmian danych musi być dostępne na platformie

Instrukcje instalacji

Pobieranie i uruchamianie skryptu

  1. Pobierz najnowszą wersję skryptu:

    Pobierz utility_script.sql

  2. Uruchom skrypt:

    1. Otwórz pobrany skrypt w programie SQL Server Management Studio (SSMS), Azure Data Studio lub preferowanym kliencie SQL.
    2. Połącz się z instancją SQL Server.
    3. Upewnij się, że masz połączenie z docelową bazą danych, w której chcesz zainstalować obiekty narzędzi.
    4. Uruchom skrypt.
  3. Sprawdź instalację:

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

Alternatywna: uruchom polecenie przy użyciu wiersza polecenia

Jeśli wolisz użyć sqlcmd:

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

Uwaga / Notatka

Zastąp YourServerName i YourDatabase rzeczywistymi nazwami swojego serwera i bazy danych. Użyj -U username -P password zamiast -E , jeśli nie używasz uwierzytelniania systemu Windows.

Przykład: Napraw uprawnienia (tylko system)

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

Przykład: naprawić uprawnienia (z dostępem do tabeli)

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

Przykłady: Konfiguracja śledzenia zmian

Tylko na poziomie bazy danych

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

Włącz we wszystkich tabelach

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

Konfiguracja oparta na schemacie

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

Określone tabele

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

Utwórz obiekty wsparcia DDL

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

Przykłady: konfiguracja usługi CDC

Tylko na poziomie bazy danych

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

Włącz we wszystkich tabelach

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

Określone tabele

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

Przejmij odpowiedzialność za istniejące instancje przechwytywania

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

Przykład: Podejście hybrydowe

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

Przykład: Oczyszczanie

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

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

Utworzone obiekty obsługi języka DDL

Następujące obiekty wsparcia DDL są tworzone w zależności od tego, czy używasz śledzenia zmian, czy CDC.

Śledzenie zmian

Typ obiektu Name Description
Tabela lakeflowDdlAudit_1_7 Przechowuje historię zmian DDL
Wyzwalacz lakeflowDdlAuditTrigger_1_7 Przechwytuje ALTER TABLE zdarzenia

Dla CDC

Typ obiektu Name Description
Tabela lakeflowCaptureInstanceInfo_1_7 Śledzi wystąpienia przechwytywania
Procedure lakeflowDisableOldCaptureInstance_1_7 Usuwa stare wystąpienie przechwytywania
Procedure lakeflowMergeCaptureInstances_1_7 Łączy dane między instancjami
Procedure lakeflowRefreshCaptureInstance_1_7 Tworzy nowe wystąpienie przechwytywania
Wyzwalacz lakeflowAlterTableTrigger_1_7 Obsługuje zmiany schematu

Ograniczenia śledzenia zmian

  • Wymaga kluczy podstawowych: tabele bez kluczy podstawowych nie mogą używać śledzenia zmian.
  • Skrypt automatycznie pomija tabele bez zestawów PKs i zaleca użycie usługi CDC.

Zachowanie specyficzne dla platformy

  • Azure SQL Database: systemowe procedury składowane są domyślnie dostępne (nie są wymagane żadne EXECUTE uprawnienia).
  • Ograniczony dostęp do widoków z zakresem serwera w usłudze Azure SQL Database, takich jak sys.change_tracking_databases.

Ścieżka aktualizacji

Aby zaktualizować, ponownie uruchom skrypt obiektów narzędzi, a następnie ponownie procedury konfiguracyjne. Skrypt odtwarza funkcje pomocnicze i usuwa jedynie replicantstarsze obiekty z wcześniejszych wersji. Pozostawia istniejące obiekty wsparcia DDL Lakeflow na miejscu, więc obecny wyzwalacz DDL nadal rejestruje zmiany schematu, dopóki nie uruchomisz ponownie procedur konfiguracji. Instrukcje znajdziesz w Kroku 1: Instalacja lub aktualizacja obiektów narzędziowych.

Co się stanie podczas uaktualniania:

  • Funkcje pomocnicze i procedury konfiguracyjne zdefiniowane przez skrypt są usuwane i odtwarzane na nowo.
  • Obiekty z prefiksami legacy replicantz wcześniejszych wersji są usuwane.
  • Istniejące obiekty wsparcia DDL Lakeflow (lakeflowDdlAudit_*, lakeflowDdlAuditTrigger_*, , lakeflowCaptureInstanceInfo_*, oraz powiązane procedury i wyzwalacze) pozostają na miejscu. Ponowne uruchomienie procedur konfiguracji przenosi je do nowej wersji. Obiekty instancji przechwytywania przesuwają lakeflowSetupChangeDataCapturesię za każdym razem, gdy ponownie uruchamiasz . Tabela audytu DDL i trigger przesuwają się tylko po ponownym uruchomieniu lakeflowSetupChangeTracking z @CreateDdlSupportingObjects = 1, ponieważ są opt-in.
  • Śledzenie zmian i cdC pozostają włączone w tabelach. Uaktualnienie nie powoduje ich wyłączenia.
  • Nie ma to wpływu na wystąpienia przechwytywania usługi CDC przez skrypt uaktualniania.

Po uruchomieniu skryptu uaktualniania ponownie uruchom procedury instalacji, aby ponownie utworzyć obiekty obsługi języka DDL dla nowej wersji:

  • lakeflowSetupChangeTracking: z , @CreateDdlSupportingObjects = 1przenosi tabelę audytową DDL i wyzwala lakeflowDdlAudit_1_7do . Przejdź tę flagę, jeśli Twoja instalacja używa DDL schema-change capture (ma tabelę lakeflowDdlAudit ) lub jeśli obiekty pozostają na starej wersji.
  • lakeflowSetupChangeDataCapture: Ponownie utworzy lakeflowCaptureInstanceInfo_1_7 i powiązane procedury i wyzwalacz.

Obie procedury są idempotentne i bezpieczne do ponownego uruchomienia z oryginalnymi parametrami konfiguracji.

Uwaga / Notatka

Aby przywrócić poprzednią wersję skryptu obiektów narzędzi, skontaktuj się z pomocą techniczną Databricks.

Schemat przechowywania wersji: objectName_majorVersion_minorVersion. Bieżące obiekty używają sufiksu _1_7 .

Najlepsze rozwiązania

  • Zawsze uruchamiaj jako db_owner lub użytkownika z równoważnymi uprawnieniami.
  • Najpierw przetestuj bazy danych nieprodukcyjnych.
  • Użyj podejścia hybrydowego do kompleksowego pokrycia.
  • Uruchom polecenie lakeflowFixPermissions po skonfigurowaniu, aby zapewnić odpowiedni dostęp użytkownika.
  • Rozważ okresy przechowywania na podstawie częstotliwości pozyskiwania.

Rozwiązywanie problemów

"Użytkownik wykonujący ten skrypt nie jest członkiem roli "db_owner"

Rozwiązanie: Wykonaj jako użytkownik z rolą db_owner

"Śledzenie zmian nie jest włączone w katalogu"

Rozwiązanie: Włącz ct na poziomie bazy danych lub pozwól, aby procedura obsłużyła ją automatycznie

"Przechwytywanie zmian danych nie jest włączone w wykazie"

Rozwiązanie: włącz usługę CDC na poziomie bazy danych lub pozwól, aby procedura obsłużyła ją automatycznie

"Tabele pominięte z powodu braku kluczy podstawowych"

Rozwiązanie: Zamiast tego użyj dla lakeflowSetupChangeDataCapture tych tabel

Integracja walidacji

Następujące obiekty narzędzi są weryfikowane przez strukturę weryfikacji języka Java:

Object Description
SqlServerUtilityObjectsSetupValidator Weryfikuje instalację obiektów narzędziowych
SqlServerChangeDataManagementSetupValidator Weryfikuje konfigurację CT/CDC
SqlServerDdlSupportObjectsSetupValidator Sprawdza poprawność obiektów obsługi języka DDL
SqlServerPermissionsSetupValidator Weryfikuje uprawnienia

Uwagi dotyczące migracji

W przypadku uaktualniania ze starszych wersji obiektów obsługi DDL (z okresu przed erą obiektów narzędziowych):

  • Skrypt automatycznie czyści starsze obiekty.
  • Nie jest wymagane czyszczenie ręczne.
  • Wersja 1.1 konsoliduje wszystkie funkcje w ujednolicone procedury.

Dodatkowe zasoby