Fouten bij het uitvoeren van dbt in een productieomgeving: Toestemmingsfouten, SQL-fouten en incrementele afwijkingen.

Fouten bij het uitvoeren van dbt-productieruns vallen in een klein aantal categorieën: het serviceaccount beschikt niet over de juiste databaserechten, de SQL werkt lokaal maar faalt in het datawarehouse, upstream-modellen zijn mislukt en hebben overgeslagen taken doorgegeven aan downstream-modellen, de inloggegevens in het productieprofiel zijn onjuist of verlopen of een incrementeel model is afgeweken van het huidige schema in de bron.

dbt-fouten werken door. Wanneer één model mislukt, markeert dbt dit als een fout en markeert elk downstream-model als overgeslagen – niet als mislukt. Een run die twintig overgeslagen modellen en één fout laat zien, heeft één hoofdoorzaak: los het upstream-model op en de overgeslagen modellen zullen werken. Elk overgeslagen model als een apart probleem behandelen is tijdverspilling.

De uitvoer van dbt-fouten is ook gestructureerd. Het fouttype (Databasefout, Compilatiefout, Runtimefout, Afhankelijkheidsfout) geeft aan op welk niveau het probleem zich bevindt voordat u het bericht leest. Door het fouttype te kennen, kunt u de mogelijke oplossingen beperken voordat u de volledige foutmelding leest.

De meest voorkomende fout bij het implementeren van dbt in een productieomgeving – met bijna vijfduizend Stack Overflow-views – is een 'toegang geweigerd'-fout bij het implementeren naar een productieschema. Het dbt-serviceaccount werkt wel in de ontwikkelomgeving (waar de machtigingen ruimer zijn), maar faalt in de productieomgeving omdat de CREATE TABLE- of CREATE VIEW-rechten nooit expliciet zijn ingesteld voor het productieschema.

Voor Snowflake is de minimale set machtigingen voor een serviceaccount in een productieomgeving als volgt:

GRANT USAGE ON DATABASE analytics_db TO ROLE dbt_prod_role;

GRANT USAGE ON SCHEMA analytics_db.prod TO ROLE dbt_prod_role;

GRANT CREATE TABLE ON SCHEMA analytics_db.prod TO ROLE dbt_prod_role;

GRANT CREATE VIEW ON SCHEMA analytics_db.prod TO ROLE dbt_prod_role;

GRANT SELECT ON ALL TABLES IN SCHEMA analytics_db.staging TO ROLE dbt_prod_role;

Om te controleren welke rechten een rol momenteel heeft: SHOW GRANTS TO ROLE dbt_prod_role;

Dit moet een eenmalige configuratiestap zijn in de productieomgeving, niet iets dat dbt zelf beheert. Organisaties die deze stap overslaan, lopen tegen een probleem met de machtigingen aan bij de eerste implementatie in de productieomgeving.

dbt compileert de SQL-code van het model voordat deze naar het datawarehouse wordt verzonden. Compilatie-errors detecteren structurele problemen, zoals een onjuiste Jinja-syntaxis, onoplosbare ref()-aanroepen en circulaire afhankelijkheden. Een meer verraderlijke categorie is echter SQL-code die succesvol compileert, maar vervolgens mislukt tijdens de uitvoering omdat het datawarehouse deze afwijst.

Dit gebeurt wanneer ontwikkelaars lokaal ontwikkelen met DuckDB of PostgreSQL en implementeren naar Snowflake of BigQuery. Functies zoals DATEADD (Snowflake) versus DATE_ADD (BigQuery), ILIKE versus LIKE en array-syntaxis verschillen per dialect. De SQL-code is syntactisch geldig in het compilatiemodel van dbt, maar ongeldig in het productiedatawarehouse.

De snelste manier om een compilatie- of uitvoeringsfout te diagnosticeren, is door de gecompileerde SQL-code direct te bekijken:

cat target/compiled/my_project/models/my_failing_model.sql

Plak deze code in de query-editor van het datawarehouse en voer deze uit. De exacte fout in het datawarehouse komt aan het licht, inclusief regelnummers en context die de foutmeldingen van dbt soms verbergen. Dit is sneller dan het lezen van dbt-logs en geeft u de onbewerkte feedback van het datawarehouse.

Een afhankelijkheidsfout treedt op wanneer een ref() verwijst naar een model dat niet in het project bestaat, is hernoemd of zich in een ander pakket bevindt dat niet is geïnstalleerd. Dit blokkeert niet alleen het verwijzende model, maar alles wat eronder valt.

Voor het debuggen kunt u eerst het model isoleren dat de fout veroorzaakt:

dbt run --select my_failing_model

Voeg vervolgens de afhankelijkheden toe:

dbt run --select +my_failing_model

Het voorvoegsel + geeft dbt de opdracht om het model en al zijn afhankelijkheden uit te voeren. Dit is de juiste manier om een specifiek model opnieuw uit te voeren nadat de fout is hersteld, zonder het hele project opnieuw uit te voeren.

Specifiek voor afhankelijkheidsfouten zal dbt compile deze detecteren voordat er SQL-query's worden uitgevoerd:

dbt compile --select +my_failing_model

Als de compilatie slaagt, maar de uitvoering mislukt, ligt het probleem bij een fout aan de kant van de datawarehouse (rechten, SQL-syntaxis) en niet bij een afhankelijkheidsprobleem aan de kant van dbt.

Runtimefouten die beginnen met "Could not find profile" of "Failed to connect" duiden op een probleem in profiles.yml, niet in de modellen of SQL. De twee meest voorkomende oorzaken zijn: de profielnaam in profiles.yml komt niet exact overeen met het profiel dat is opgegeven in dbt_project.yml of de productiegegevens (serviceaccountsleutel, OAuth-token, warehouse-eindpunt) zijn onjuist of verlopen.

Bij een onjuiste profielnaam:

# dbt_project.yml zegt: profile: my_project

# profiles.yml moet exact het volgende bevatten: my_project: # niet my_project_prod, niet MyProject

target: prod

uitvoer:

prod: ...

Een verschil van één teken in de profielnaam veroorzaakt een "Could not find profile"-fout die lijkt op een configuratieprobleem, maar in werkelijkheid een typefout is.

De eerste diagnostische stap bij een verbindingsfout is dbt debug. Deze controleert het profiel, het doel, de warehouse-connectiviteit en de dbt-versie in één commando en rapporteert welke specifieke controle is mislukt. Dit duurt minder dan tien seconden en sluit de meest voorkomende oorzaken uit voordat u naar SQL gaat kijken.

Incrementele modellen bouwen voort op bestaande tabellen, alleen nieuwe rijen worden bij elke run toegevoegd. Deze efficiëntie gaat gepaard met een kwetsbaarheid: wanneer het bronschema verandert (een nieuwe kolom verschijnt, een bestaande kolom wordt hernoemd of het gegevenstype verandert), komt de INSERT-instructie van het incrementele model mogelijk niet meer overeen met de structuur van de doeltabel.

Het symptoom is een databasefout in een incrementeel model dat eerder wel werkte. De foutmelding vermeldt een onjuiste kolomnaam of een incompatibiliteit van het gegevenstype.

De oplossing is een volledige refresh, waarbij de tabel wordt verwijderd en opnieuw wordt opgebouwd vanuit het huidige schema:

dbt run --full-refresh --select my_incremental_model

Dit is de juiste tool voor schema-drift. Het lost het directe probleem op, maar voorkomt niet dat het zich opnieuw voordoet. Voor incrementele productiemodellen zorgt het toevoegen van een contract (kolomdefinities in het .yml-bestand van het model) ervoor dat schemawijzigingen tijdens het compileren worden gedetecteerd in plaats van tijdens de uitvoering:

models:

- name: my_incremental_model config:

contract:

enforced: true

columns:

• name: event_id

data_type: varchar

Met contracthandhaving zal dbt een foutmelding geven tijdens het compileren als het bronschema niet langer overeenkomt met het contract, nog voordat er SQL-query's worden uitgevoerd.

Een van de meest betrouwbare manieren om een dbt Cloud-productiejob op het slechtst mogelijke moment te laten mislukken, is door deze te configureren met persoonlijke ontwikkelaarsgegevens in plaats van een serviceaccount. Wanneer de ontwikkelaar zijn wachtwoord wijzigt, zijn API-sleutel roteert of zijn account deactiveert, mislukt de productiejob onmiddellijk.

dbt Cloud-taken moeten altijd gebruikmaken van serviceaccountgegevens die gekoppeld zijn aan een niet-persoonlijke identiteit, een speciaal dbt Cloud-serviceaccount, een machinegebruiker of een OAuth-identiteit die niet is gekoppeld aan de arbeidsstatus van een specifieke persoon.

Voor dbt Core-pipelines geldt dezelfde regel voor profiles.yml in CI/CD: omgevingsvariabelen voor referenties ({{ env_var('SNOWFLAKE_ACCOUNT') }}), geen hardgecodeerde waarden of persoonlijke tokens. Hardgecodeerde persoonlijke referenties in CI/CD-pipelines vormen niet alleen een betrouwbaarheidsrisico, maar ook een beveiligingsrisico.

MetricSign integreert met dbt Cloud via de dbt Cloud API. Wanneer een job mislukt, maakt MetricSign een job_failed-incident aan en extraheert de details van de uitvoeringsstap, het specifieke model dat is mislukt, het fouttype en het foutbericht en toont deze als een root_cause_hint bij het incident.

In plaats van in te loggen op dbt Cloud, de uitvoering te zoeken, de mislukte stap uit te vouwen en de foutmelding te lezen, ziet u iets als: dim_customers: Databasefout, kolom 'email' bestaat niet in de incidentmelding. Het onderzoek start direct bij het juiste model.

MetricSign koppelt ook dbt lineage (uit manifest.json) aan de downstream Power BI-datasets die afhankelijk zijn van het mislukte model. Als een dbt-model dat een dataset voedt, mislukt, zijn de getroffen rapporten zichtbaar in de incidentcontext, voordat iemand Power BI opent en stale data ontdekt.