De installatiewizard verbergt vijf verschillende foutscenario's achter één foutmelding.
Discussies op het Databricks-communityforum over de SQL Server-connector van Lakeflow Connect vertonen een terugkerend patroon: de database-configuratie mislukt, de foutmelding is vrijwel nutteloos en de engineer besteedt uren aan het aanpassen van machtigingen die mogelijk helemaal niet het probleem zijn.
De configuratiestap voert wel degelijk werk uit op de achtergrond. Het controleert of het hulpprogramma-script correct is geïnstalleerd of Change Tracking (CDC) is ingeschakeld op zowel database- als tabelniveau, bevestigt dat de gebruiker die de gegevens opneemt de juiste machtigingen heeft en valideert of DDL-ondersteuningsobjecten bestaan voor schema-evolutie. Elk van deze controles kan mislukken, maar de wizard meldt slechts één algemene fout.
Hieronder volgen de vijf oorzaken, gerangschikt op hoe vaak ze in de praktijk voorkomen:
- De gebruiker die het hulpprogramma-script uitvoerde, was geen lid van de groep db_owner, waardoor de opgeslagen procedures onvolledig zijn geïnstalleerd of stilzwijgend machtigingen hebben overgeslagen.
- De CDC-vastleggingsinstanties zijn vol. SQL Server staat maximaal twee per tabel toe en als beide bezet zijn door niet-Lakeflow-instanties, kan de connector de instantie met het voorvoegsel lakeflow_ niet aanmaken.
- De ingestiegebruiker heeft geen SELECT-rechten op sys.change_tracking_tables, sys.change_tracking_databases of het cdc-schema.
- De versie van het hulpprogrammascript is verouderd, de huidige versie is 1.5 en oudere versies gebruiken een ander voorvoegsel voor vastleggingsinstanties (New_ in plaats van lakeflow_) dat de nieuwste gateway niet herkent.
- Change tracking of CDC is ingeschakeld op databaseniveau, maar niet op de specifieke tabellen die u voor ingestie hebt geselecteerd.
Elk van deze problemen vereist een andere oplossing. In de rest van dit bericht wordt uitgelegd hoe u kunt controleren welke oplossing op u van toepassing is.
db_owner is vereist voor de configuratie, niet voor het importeren van gegevens en dat onderscheid zorgt voor verwarring.
De Databricks-documentatie stelt duidelijk dat de gebruiker die het utility-objectscript uitvoert, lid moet zijn van de groep db_owner. Er staat echter ook dat de ingestiegebruiker alleen specifieke SELECT-rechten nodig heeft. Engineers interpreteren dit als "mijn ingestiegebruiker heeft geen db_owner nodig", wat correct is en voeren vervolgens het utility-script uit als de ingestiegebruiker. Het script loopt niet vast. Het installeert een aantal objecten, slaat andere stilzwijgend over en de setup-stap wijst de onvolledige installatie later af.
Om dit te controleren, maakt u verbinding als een gebruiker met db_owner en voert u het volgende uit:
```sql SELECT dbo.lakeflowUtilityVersion_1_5() AS UtilityVersion;
SELECT dbo.lakeflowDetectPlatform() AS Platform;
```
Als een van beide functies niet bestaat, is het script niet voltooid. Om de rol db_owner toe te kennen aan uw setup-gebruiker in moderne SQL Server (2012+):
```sql USE [uw_database];
ALTER ROLE db_owner ADD MEMBER [uw_setup_gebruiker];
GO ```
Gebruik in plaats daarvan sp_addrolemember in oudere instanties of beperkte omgevingen:
```sql USE [uw_database];
EXEC sp_addrolemember 'db_owner', 'uw_setup_gebruiker';
GO ```
Nadat u de rol hebt toegekend, voert u het volledige utility_script.sql opnieuw uit. Ga er niet van uit dat een gedeeltelijke installatie kan worden hersteld, het script is ontworpen om idempotent te zijn, dus een schone herstart is veiliger dan proberen individuele objecten te patchen. Zodra het script is voltooid, voert u de verificatiefuncties opnieuw uit. Beide zouden waarden zonder fouten moeten retourneren.
Een veelvoorkomende variant van dit probleem doet zich voor bij Azure SQL Database, waar de gebruiker die de installatie uitvoert lid moet zijn van de serverrol ##MS_DatabaseConnector## in plaats van individuele masterdatabase-toegang. Als u Azure SQL Managed Instance gebruikt, hebt u VIEW ANY DATABASE op serverniveau nodig, plus expliciete toegang tot de masterdatabase. Het platform is van belang.
De beschikbare CDC-opname-instance-slots raken stilletjes vol.
SQL Server hanteert een strikte limiet van twee capture-instanties per tabel. Lakeflow Connect heeft minimaal één beschikbare plek nodig om zijn lakeflow_ Deze fout is bijzonder frustrerend, omdat CDC ingeschakeld lijkt te zijn. De controle op databaseniveau slaagt. De controle op tabelniveau slaagt. Maar de connector kan geen eigen capture-instantie creëren en de configuratiestap mislukt. Om het gebruik van capture-instanties per tabel te controleren: ```sql
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; `` Als een tabel twee capture-instanties heeft en geen van beide begint met lakeflow_, dan hebt u het probleem gevonden. Uw opties: verwijder een van de bestaande capture-instanties als deze niet langer nodig is of schakel die tabel over naar change tracking in plaats van CDC. Change tracking werkt voor elke tabel met een primaire sleutel, gebruikt minder overhead op de bron en heeft geen limiet van twee instanties. Als u een upgrade uitvoert vanaf een oudere versie van het utility-script, ziet u mogelijk capture-instanties met het voorvoegsel New_ in plaats van lakeflow_. Het uitvoeren van de nieuwste utility_script.sql (versie 1.5) voert deze migratie automatisch uit, maar alleen als er tijdens de overgang een capture-instantie beschikbaar is voor de nieuwe naamgevingsconventie. Stop de gateway voordat u de upgrade uitvoert. Het script vervangt namelijk DDL-ondersteuningsobjecten en een actieve pipeline verliest DDL-auditgebeurtenissen tijdens de vervanging. De hybride aanpak die Databricks aanbeveelt – wijzigingsregistratie voor tabellen met primaire sleutels en CDC voor tabellen zonder – omzeilt het slotprobleem volledig voor de meeste schema's. 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 systeemcatalogus, toegang tot wijzigingsdetectie en SELECT-toegang op tabelniveau. Voor toegang tot de systeemcatalogus 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-premises 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 u de procedures hebt uitgevoerd zonder @User op te geven, zijn de machtigingen niet verleend. Voer lakeflowFixPermissions uit om de ontbrekende rechten te herstellen: ```sql
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 u 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: ```sql
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: ```sql
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 uw 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 uw ingestiepipeline zelden draait of langdurig downtime ondervindt, kunt u 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 u 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 u 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 (firewallregels, 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 permissiefouten, 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._1-instantie te creëren. Als beide plekken bezet zijn door bestaande capture-instanties van andere systemen, een oudere replicatie-configuratie, een zelfontwikkelde CDC-client of een eerdere Lakeflow-installatie met het verouderde voorvoegsel New_, kan de connector niet verder.
Het toegangsgebied van de gebruiker voor gegevensinvoer is groter dan het lijkt.
Het inschakelen van wijzigingsdetectie op databaseniveau heeft geen zin zonder activering op tabelniveau.
Voer de verificatiequery's uit vóór de wizard, niet erna.
Gerelateerde integraties