Lakeflow Connect SQL Server: Waarom de database-configuratiestap steeds mislukt

Zelfs nadat het hulpprogramma-script succesvol is uitgevoerd, kan de gebruiker die de gegevens opneemt nog steeds onvoldoende machtigingen hebben, waardoor de configuratiestap mislukt. De vereiste machtigingen vallen in drie categorieën: toegang tot de systeem catalogus, toegang tot wijzigingsdetectie en SELECT-toegang op tabelniveau.

Voor toegang tot de systeem catalogus heeft de gebruiker die de gegevens opneemt SELECT-toegang nodig op sys.databases, sys.schemas, sys.tables, sys.columns, sys.key_constraints, sys.foreign_keys, sys.check_constraints, sys.default_constraints, sys.change_tracking_tables, sys.change_tracking_databases, sys.objects, sys.triggers, sys.indexes en sys.index_columns. Het vereist ook EXECUTE-rechten op sp_tables, sp_columns_100, sp_pkeys en sp_statistics_100, plus VIEW DATABASE PERFORMANCE STATE.

Specifiek voor CDC heeft de gebruiker SELECT-rechten nodig op het volledige cdc-schema. Op on-premise en RDS-instanties is ook VIEW SERVER STATE vereist om sys.dm_server_services op te vragen, wat Lakeflow gebruikt om te controleren of SQL Server Agent actief is. Als Agent is gestopt, worden CDC-wijzigingen niet vastgelegd en zal de connector weigeren verder te gaan.

De procedures lakeflowSetupChangeTracking en lakeflowSetupChangeDataCapture van het hulpprogramma-script verlenen automatisch CDC- en CT-specifieke machtigingen, maar alleen als de parameter @User is ingesteld. Als je de procedures hebt uitgevoerd zonder @User op te geven, zijn de machtigingen niet verleend. Voer lakeflowFixPermissions uit om de ontbrekende rechten te herstellen:

EXEC dbo.lakeflowFixPermissions

@User = 'uw_ingestion_user',

@Tables = 'ALL';

Dit verleent SELECT-rechten op systeem- en tabelniveau. Het is veilig om dit herhaaldelijk uit te voeren — de procedure is idempotent. Controleer na het uitvoeren de configuratiestap nogmaals. Als je zich richt op specifieke schema's in plaats van alle tabellen, vervang dan 'ALL' door 'SCHEMAS:Sales,HR' of een door komma's gescheiden tabellijst om het principe van minimale bevoegdheden te volgen.

Dit is de meest voorkomende vorm van valse zekerheid. Een engineer schakelt wijzigingsregistratie in op databaseniveau en gaat ervan uit dat tabellen dit automatisch overnemen. Dat is niet het geval. Wijzigingsregistratie moet expliciet voor elke tabel worden ingeschakeld en CDC (Change Data Capture) moet expliciet worden ingeschakeld met een capture-instantie per tabel.

Om te controleren of wijzigingsregistratie op databaseniveau is ingeschakeld:

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();

Om te controleren voor welke tabellen daadwerkelijk wijzigingsregistratie is ingeschakeld:

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;

``

Als je doeltabellen ontbreken in deze resultaatset, mislukt de installatiestap ongeacht de configuratie op databaseniveau. De oplossing is eenvoudig: voer de installatieprocedure opnieuw uit met de juiste tabellijst:

sql EXEC dbo.lakeflowSetupChangeTracking

@Tables = 'Sales.Orders,Production.Products',

@User = 'your_ingestion_user',

@Retention = '2 DAYS';

``

De parameter @Retention bepaalt hoe lang de wijzigingsgeschiedenis wordt bewaard voordat deze door de automatische opschoning wordt verwijderd. Twee dagen is de aanbeveling van Databricks voor de meeste workloads, maar als je ingestie pipeline zelden draait of langdurig downtime ondervindt, kunt je deze periode verlengen. Als het bewaarvenster verloopt voordat de pipeline de wijzigingen heeft gelezen, activeert Lakeflow een volledige refresh van die tabel. Dit is een kostbare bewerking bij grote datasets die ook de downstream watermarks reset.

Voor CDC kunt je de inschakeling op tabelniveau controleren door cdc.change_tables op te vragen. Als een tabel is_cdc_enabled = 1 heeft op databaseniveau, maar geen vermelding in cdc.change_tables, is de capture-instantie nooit aangemaakt. Voer lakeflowSetupChangeDataCapture uit, gericht op die specifieke tabellen.

De foutmeldingen van de installatiewizard worden met elke nieuwe Databricks runtime-release beter, maar begin 2026 worden meerdere foutmodi nog steeds samengevoegd in generieke berichten. De meest betrouwbare aanpak is om de volledige verificatiesuite uit te voeren voordat je de installatiestap probeert.

Een checklist in SQL:

```sql -- 1. Controleer de versie van het hulpprogrammascript SELECT dbo.lakeflowUtilityVersion_1_5() AS UtilityVersion;

-- 2. Controleer de platformdetectie SELECT dbo.lakeflowDetectPlatform() AS Platform;

-- 3. Controleer de wijzigingsdetectie op databaseniveau SELECT * FROM sys.change_tracking_databases WHERE database_id = DB_ID();

-- 4. Controleer de wijzigingsdetectie op tabelniveau SELECT SCHEMA_NAME(t.schema_id) + '.' + t.name FROM sys.change_tracking_tables ct JOIN sys.tables t ON ct.object_id = t.object_id;

-- 5. Bevestig CDC-databaseniveau SELECT is_cdc_enabled FROM sys.databases WHERE database_id = DB_ID();

-- 6. Bevestig CDC-opname-instanties SELECT capture_instance FROM cdc.change_tables;

-- 7. Bevestig machtigingen voor de ingestiegebruiker EXEC dbo.lakeflowFixPermissions

@User = 'uw_ingestiegebruiker',

@Tables = 'ALLE';

``

Als elke query de verwachte resultaten oplevert en lakeflowFixPermissions zonder fouten wordt voltooid, zou de configuratiestap moeten slagen. Als het nog steeds mislukt, controleer dan de logboeken van de gateway-clusterdriver. Download deze van de pagina met pipelinedetails en zoek naar INGESTION_GATEWAY_CONNECTION_ERROR of INGESTION_GATEWAY_INTERNAL_ERROR. De eerste wijst op problemen op netwerkniveau (firewall regels, onjuiste hostnaam of poort), terwijl de laatste inspectie op logniveau vereist voor stacktraces.

Voor teams die meerdere Lakeflow Connect-pipelines uitvoeren over verschillende SQL Server instanties, groepeert MetricSign ingestiefouten op basis van de hoofdoorzaak. Hierbij worden permissie fouten, verbindingstime-outs en configuratieproblemen met CDC onderscheiden. Zo ziet de dienstdoende engineer één incident per onderliggend probleem in plaats van één melding per mislukte pipeline. Dit is belangrijk wanneer een enkele wachtwoordwijziging in Active Directory de ingestie in twaalf databases tegelijk verstoort.