使用工具物件腳本來配置 SQL Server 以便進行資料匯入

完成 SQL Server 資料庫設定工作，以使用 Lakeflow Connect 內嵌至 Azure Databricks。

需求

執行指令碼的使用者必須是角色的 db_owner 成員。這個角色只用於執行設定腳本，對於擷取使用者則不需要。

要將使用者加入 db_owner 角色，請使用以下其中一種方法：

現代 SQL Server（2012+）：應用 ALTER ROLE

USE [your_database];
ALTER ROLE db_owner ADD MEMBER [your_setup_user];
GO

舊有 SQL Server 或受限環境：用途 sp_addrolemember

USE [your_database];
EXEC sp_addrolemember 'db_owner', 'your_setup_user';
GO

CT 設定時，平台上必須具備變更記錄功能。
針對 CDC 設定：平台上必須提供變更資料擷取功能。

步驟 1：安裝或升級工具物件

此步驟會安裝 SQL Server 安裝所需的公用程式預存程式和函式。如需安裝內容的詳細資訊，請參閱 SQL Server 公用程式物件腳本參考。

同一個腳本同時處理首次安裝與從前一個版本升級。請依照下方編號步驟操作。標示為（僅限升級）的步驟僅適用於已安裝先前版本的工具物件時。第一次安裝的話可以跳過它們。

Important

（僅限升級）執行腳本前，請先停止閘道（以閘道為基礎的管線），或暫停管線（整合式 CDC）。暫停可以避免結構變更快速失敗，避免在短暫切換期間需要重試。

下載劇本：

下載utility_script.sql
在 SQL Server Management Studio （SSMS）、Azure Data Studio 或您慣用的 SQL 用戶端中開啟腳本。
以具有 db_owner 角色的使用者身分連線至您的 SQL Server 執行個體。
請確定您已連線到目標資料庫。
（僅限升級）暫停資料擷取：停止閘道（以閘道為基礎的管線），或暫停管線（整合式 CDC）。
執行腳本。升級時，腳本會重建工具函數，並只移除舊有 replicant的 -前綴物件。它會保留你現有的 DDL 支援物件，所以目前的 DDL 觸發器會持續捕捉結構變更，直到你在下一步重新執行設定程序。
（僅限升級）針對你使用的每種擷取方法，重新執行設定程序：如果你使用變更追蹤，請執行 lakeflowSetupChangeTracking；如果你使用 CDC，請執行 lakeflowSetupChangeDataCapture。這會將您的物件移轉到新版本，並恢復擷取使用者的權限。僅傳遞 @User。您不需要 @Tables，因為變更追蹤和 CDC 在升級期間會於您的資料表上持續保持啟用狀態。
```
-- If you use change tracking:
EXEC dbo.lakeflowSetupChangeTracking
    @User = 'your_ingestion_user';  -- omit @User if you did not pass it originally

-- If you use CDC:
EXEC dbo.lakeflowSetupChangeDataCapture
    @User = 'your_ingestion_user';  -- omit @User if you did not pass it originally
```
請再次傳遞任何非預設選項，以確保升級能保留你的設定：
- 變更追蹤： 預設情況下，不會建立 DDL 稽核資料表和觸發器，因此大多數升級在此無須額外指定任何內容。如果您的安裝使用 DDL 架構變更擷取（它有一個 lakeflowDdlAudit 資料表），請在 lakeflowSetupChangeTracking 上傳遞 @CreateDdlSupportingObjects = 1，將這些物件移轉到新版本。在這個選項出現之前的安裝系統會自動建立這些標記，所以如果你依賴 DDL 擷取，即使從未設定過，也要包含這個標記。
- CDC: 如果您在@AllowDisablePreExistingCaptureInstances = 1上使用lakeflowSetupChangeDataCapture，請再次加入。

驗證安裝：

SELECT dbo.lakeflowUtilityVersion() AS UtilityVersion;
SELECT dbo.lakeflowDetectPlatform() AS Platform;

（僅限升級）恢復擷取：恢復閘道或管線。

備註

db_owner這個角色僅對執行此設定腳本的使用者必要。資料匯入使用者（在後續步驟的參數中 @User 指定）只需設定步驟所賦予的特定權限。詳情請參閱 Microsoft SQL Server 資料庫使用者需求。

備註

（僅限升級）避免在升級期間對追蹤資料表進行結構變更。切換以交易形式執行，因此同時進行的結構變更不會遺失，但可能短暫阻塞或快速失敗，需要重試直到切換完成。

步驟 2：啟用變更追蹤（適用於具有主索引鍵的資料表）

變更追蹤是一種輕量型機制，可追蹤表格列的變更。此步驟會在資料庫層級對指定的資料表啟用 CT。若要同時擷取結構變更（DDL），請通過 @CreateDdlSupportingObjects = 1 以建立 DDL 支援物件。這項功能需由使用者主動選擇加入，且預設為關閉。如需詳細資訊，請參閱 lakeflowSetupChangeTrackingSQL Server 公用程式物件指令碼參考。

-- Enable change tracking on specific tables
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'Sales.Orders,Production.Products,HR.Employees',
    @User = 'your_ingestion_user',
    @Retention = '2 DAYS';

替代選項：

對於所有具有主索引鍵的資料表： @Tables = 'ALL'
針對特定結構描述： @Tables = 'SCHEMAS:Sales,HR,Production'
僅適用於資料庫層級設定（不啟用資料表）： @Tables = NULL

步驟 3：啟用變更資料擷取（適用於沒有主索引鍵的資料表）

CDC 會擷取插入、更新和刪除活動，對於沒有主索引鍵的資料表特別有用。此步驟會在資料庫層級啟用 CDC、設定擷取執行個體管理，並建立觸發器以自動處理結構描述變更。如需詳細資訊，請參閱 lakeflowSetupChangeDataCaptureSQL Server 公用程式物件指令碼參考。

-- Enable CDC on specific tables (particularly those without primary keys)
EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = 'Staging.ImportData,Logs.AuditTrail',
    @User = 'your_ingestion_user';

替代選項：

對於所有表格： @Tables = 'ALL'
針對特定結構描述： @Tables = 'SCHEMAS:Sales,HR'
僅適用於資料庫層級設定： @Tables = NULL

若要讓 Lakeflow Connect 接管資料表中既有（非 Lakeflow）的 CDC 擷取實例，而非保留原位，請設定 @AllowDisablePreExistingCaptureInstances = 1。

備註

您可以使用變更追蹤或 CDC，也可以同時使用兩者。 Databricks 建議對具有主索引鍵的資料表（步驟 2）使用變更追蹤，並針對沒有主索引鍵的資料表使用 CDC （步驟 3），以取得全面的涵蓋範圍。

擷取實例管理

Lakeflow Connect 採用基於前綴的命名慣例來管理 CDC 擷取實例，而不影響其他系統或程序所建立的先前擷取實例。

湖流量捕捉實例命名

Lakeflow Connect 會根據以下命名模式建立並管理擷取實例：

lakeflow_<schema>_<table>_1
lakeflow_<schema>_<table>_2

Lakeflow Connect 只管理符合此命名模式的擷取實例。先前具有不同名稱的現有捕捉實例會被保留，且不會受到 Lakeflow 操作的影響。

備註

在 1.4 之前的實用腳本版本中，Lakeflow Connect 使用 capture instance 的 New_ 前綴（例如 New_schema_table_1）。如果你是從舊版本升級，請執行更新過的工具腳本，以遷移到命名慣例lakeflow_。腳本在轉換過程中會自動處理與現有 New_-前綴擷取實例的向下相容性。

擷取實例槽位需求

SQL Server 每表最多允許 2 個擷取實例。若要讓 Lakeflow Connect 與 CDC 搭配運作：

Lakeflow 必須有至少兩個捕捉實例插槽中的一個可用，才能建立其 lakeflow_ 前綴實例。
如果兩個時段都已被非 Lakeflow 的擷取實例佔據，Lakeflow Connect 無法建立並管理自己的擷取實例。雖然 Lakeflow 可以從既有的擷取實例讀取資料，但無法執行完整的刷新或結構演化操作。

小提示

如果兩個擷取實例欄位都被佔用，請改用變更追蹤，或移除現有的擷取實例（如果不再需要）。

與其他 CDC 使用者共存

Lakeflow Connect 可與其他 CDC 消費者安全共存於同一表格：

在所有 Lakeflow 操作期間，既有的擷取實例都會被保留（例如完整刷新與結構演化）。
Lakeflow 只有在需要時才會刪除並重建自己的 lakeflow_ 前綴實例。
其他從非湖流擷取實例消耗 CDC 資料的系統則持續運作且不中斷。

重建 Lakeflow 擷取實例的操作：

以下操作會導致 Lakeflow 刪除並重新建立其 lakeflow_ 前綴的捕捉實例，但不包括其他實例：

全面更新作業
向資料表新增欄位（ADD COLUMN）

範例情境：

如果一個資料表中已有一個名為 my_app_cdc：

Lakeflow Connect 會產生 lakeflow_schema_table_1。
兩個捕獲實例安全地共存。
當 Lakeflow 進行完整刷新或架構演化時，它只會重建 lakeflow_schema_table_1。
該 my_app_cdc 實例保持不變，並持續為另一系統運作。

步驟 4：授予其他權限（如果需要）

此步驟會授與匯入使用者必要的系統和資料表層級許可權。雖然步驟 2 和 3 會授與 CT 和 CDC 特定的權限，但此步驟可確保使用者擁有所有必要的 SELECT 權限。如需詳細資訊，請參閱 lakeflowFixPermissionsSQL Server 公用程式物件指令碼參考。

-- Grant system-level and table-level permissions
EXEC dbo.lakeflowFixPermissions
    @User = 'your_ingestion_user',
    @Tables = 'Sales.Orders,Production.Products,HR.Employees';

替代選項：

對於所有表格： @Tables = 'ALL'
僅限系統權限： @Tables = NULL
具體模式： @Tables = 'SCHEMAS:Sales,HR'

備註

步驟 2 和 3 中的設定程序會自動授與必要的 CT 和 CDC 許可，但如果許可被撤銷或需要授予額外的資料表層級 SELECT 許可，您可能必須執行此程序。

步驟 5：驗證設定

執行下列查詢，以確認資料庫和資料表的變更追蹤和 CDC 已正確設定。

-- Check Change Tracking status
SELECT
    d.name AS DatabaseName,
    ctd.is_auto_cleanup_on,
    ctd.retention_period,
    ctd.retention_period_units_desc
FROM sys.change_tracking_databases ctd
INNER JOIN sys.databases d ON ctd.database_id = d.database_id
WHERE d.name = DB_NAME();

-- Check tables with Change Tracking enabled
SELECT
    SCHEMA_NAME(t.schema_id) + '.' + t.name AS TableName,
    ct.is_track_columns_updated_on,
    ct.begin_version,
    ct.cleanup_version
FROM sys.change_tracking_tables ct
INNER JOIN sys.tables t ON ct.object_id = t.object_id;

-- Check CDC status
SELECT
    DB_NAME() AS DatabaseName,
    is_cdc_enabled
FROM sys.databases
WHERE database_id = DB_ID();

-- Check tables with CDC enabled
SELECT
    SCHEMA_NAME(t.schema_id) + '.' + t.name AS TableName,
    ct.capture_instance,
    ct.start_lsn,
    ct.create_date
FROM cdc.change_tables ct
INNER JOIN sys.tables t ON ct.source_object_id = t.object_id;

升級工具物件

升級時使用與首次安裝相同的腳本。遵循步驟 1：安裝或升級工具物件，包括標示為（僅限升級）的步驟，涵蓋暫停資料擷取、重執行設定程序及恢復資料擷取。

備註

若要還原到先前版本的工具物件腳本，請聯絡 Databricks 支援團隊。

範例：混合式方法

備註

為了簡單起見，此範例用於 'ALL' 在所有表上啟用 CT 和 CDC。對於生產用途，請考慮此頁面上的常見案例，以特定結構描述或資料表為目標。

-- Step 1: Already completed (script installed)

-- Step 2 & 3: Enable both CT and CDC
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'ALL',
    @User = 'lakeflow_user',
    @Retention = '2 DAYS';

EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = 'ALL',
    @User = 'lakeflow_user';

-- Step 4: Grant all necessary permissions
EXEC dbo.lakeflowFixPermissions
    @User = 'lakeflow_user',
    @Tables = 'ALL';

常見場景

案例 1：僅變更追蹤（特定結構描述）

EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'SCHEMAS:Sales,Production',
    @User = 'lakeflow_user',
    @Retention = '2 DAYS';

EXEC dbo.lakeflowFixPermissions
    @User = 'lakeflow_user',
    @Tables = 'SCHEMAS:Sales,Production';

情境 2：僅限 CDC（特定資料表）

EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = 'Staging.ImportData,Logs.AuditTrail,dbo.TempRecords',
    @User = 'lakeflow_user';

EXEC dbo.lakeflowFixPermissions
    @User = 'lakeflow_user',
    @Tables = 'Staging.ImportData,Logs.AuditTrail,dbo.TempRecords';

案例 3：混合方法（某些資料結構的 CT，特定資料表的 CDC）

-- Enable CT on transactional schemas
EXEC dbo.lakeflowSetupChangeTracking
    @Tables = 'SCHEMAS:Sales,HR',
    @User = 'lakeflow_user',
    @Retention = '3 DAYS';

-- Enable CDC on specific staging tables without primary keys
EXEC dbo.lakeflowSetupChangeDataCapture
    @Tables = 'Staging.ImportData,Logs.AuditTrail',
    @User = 'lakeflow_user';

-- Grant permissions on all tables
EXEC dbo.lakeflowFixPermissions
    @User = 'lakeflow_user',
    @Tables = 'ALL';

其他資源

SQL Server 公用程式物件指令碼參考
將 Microsoft SQL Server 配置以整合至 Azure Databricks
Microsoft SQL Server 資料庫使用者需求
追蹤 SQL Server 檔中的資料變更（SQL Server）

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-09-30

使用工具物件腳本來配置 SQL Server 以便進行資料匯入

需求

步驟 1：安裝或升級工具物件

步驟 2：啟用變更追蹤 （適用於具有主索引鍵的資料表）

步驟 3：啟用變更資料擷取 （適用於沒有主索引鍵的資料表）

擷取實例管理

湖流量捕捉實例命名

擷取實例槽位需求

與其他 CDC 使用者共存

步驟 4：授予其他權限（如果需要）

步驟 5：驗證設定

升級工具物件

範例：混合式方法

常見場景

案例 1：僅變更追蹤 （特定結構描述）

情境 2：僅限 CDC（特定資料表）

案例 3：混合方法（某些資料結構的 CT，特定資料表的 CDC）

其他資源

意見反應

其他資源

步驟 2：啟用變更追蹤（適用於具有主索引鍵的資料表）

步驟 3：啟用變更資料擷取（適用於沒有主索引鍵的資料表）

案例 1：僅變更追蹤（特定結構描述）