Outils de scaffolding pour la documentation dbt

Deux outils open-source gèrent les parties mécaniques de la documentation dbt : générer des fichiers YAML vides et propager les descriptions existantes dans le DAG. Aucun des deux n’écrit des descriptions — ils réduisent la surface qui nécessite une attention humaine ou IA.

dbt-codegen

Le package officiel dbt-codegen de dbt Labs génère le scaffolding YAML depuis votre schéma d’entrepôt. Pointez-le vers un modèle et il produit un bloc YAML complet avec chaque nom de colonne et un champ description vide :

dbt run-operation generate_model_yaml --args '{"model_names": ["base__stripe__payments"]}'

La sortie vous donne la structure — nom du modèle, tous les noms de colonnes, descriptions vides. Plus besoin de taper manuellement les noms de colonnes ou de découvrir trois mois plus tard que quelqu’un a ajouté des colonnes que vous n’avez jamais documentées.

Si vous utilisez le pattern codegen + Claude Code, le flag upstream_descriptions: true extrait les descriptions depuis les définitions de sources ou les modèles en amont pour que vous ne re-décriviez pas des colonnes qui ont déjà de la documentation :

dbt run-operation generate_model_yaml --args '{"model_names": ["base__ga4__events"], "upstream_descriptions": true}'

dbt-codegen lit le modèle compilé, extrait la liste de colonnes depuis l’entrepôt, et génère le YAML. Il n’écrit pas de descriptions, n’ajoute pas de tests, et ne prend pas de décisions. Le résultat est un template YAML complet avec chaque nom de colonne et des champs description vides.

dbt-osmosis

dbt-osmosis adopte une approche fondamentalement différente. Au lieu de générer un scaffolding vide, il propage les descriptions existantes dans votre DAG en suivant le lignage. Si vous avez décrit customer__email dans votre modèle base, dbt-osmosis copie cette description dans chaque modèle en aval qui utilise la même colonne.

La commande centrale :

dbt-osmosis yaml refactor

Cette seule commande fait plusieurs choses à la fois :

• Génère de nouveaux fichiers YAML pour les modèles qui n’en ont pas
• Injecte les colonnes de votre entrepôt dans le YAML existant (capturant les colonnes ajoutées depuis le dernier passage de documentation)
• Propage les descriptions des modèles en amont vers les modèles en aval
• Supprime les colonnes périmées qui n’existent plus dans le modèle compilé

Sur un projet avec 200+ modèles, exécuter dbt-osmosis yaml refactor propage généralement des descriptions vers 30 à 50 % des colonnes précédemment non documentées. La raison est simple : les noms de colonnes se répètent entre les couches. customer_id apparaît dans votre modèle base, vos jointures intermédiaires, et vos marts. S’il est documenté une fois à la couche base, osmosis copie cette description partout où il apparaît en aval.

Configurer comme hook pre-commit

La vraie valeur de dbt-osmosis vient de son automatisation. Configurez-le comme hook pre-commit et il s’exécute à chaque commit, maintenant les fichiers YAML synchronisés avec votre schéma réel :

repos:
  - repo: local
    hooks:
      - id: dbt-osmosis
        name: dbt-osmosis yaml refactor
        entry: dbt-osmosis yaml refactor
        language: system
        pass_filenames: false

Cela capture le problème courant de dérive : quelqu’un ajoute une colonne à un modèle, le YAML n’est pas mis à jour, et la documentation diverge progressivement de la réalité. Avec osmosis qui s’exécute à chaque commit, le YAML reflète toujours le schéma actuel.

Workflow combiné

dbt-codegen — scaffolding initial. Crée des fichiers YAML depuis zéro lors de l’ajout de nouveaux modèles. Opération ponctuelle par modèle.

dbt-osmosis — maintenance continue. Maintient le YAML synchronisé avec les changements de schéma, propage les descriptions à mesure que des modèles en aval sont ajoutés, supprime les colonnes supprimées.

Un workflow pratique :

1. Exécuter dbt-codegen lors de l’ajout d’un nouveau modèle pour générer la structure YAML initiale
2. Écrire les descriptions pour les colonnes qui sont genuinement nouvelles (pas héritées de l’amont)
3. Exécuter dbt-osmosis yaml refactor pour propager ces descriptions à tous les modèles en aval
4. Configurer osmosis comme hook pre-commit pour qu’il s’exécute automatiquement à l’avenir

Après ce workflow, les colonnes non documentées se limitent à celles avec une signification métier genuinement nouvelle non décrite nulle part en amont — nécessitant une attention humaine ou IA.

Ce que ces outils ne font pas

Aucun des deux n’écrit de descriptions. Ils résolvent des problèmes structurels : fichiers YAML manquants, colonnes manquantes, et descriptions présentes à un endroit mais pas propagées en aval. Sur un projet de 200 modèles, le scaffolding et la propagation peuvent faire passer la couverture de 20 % à 60 % sans écrire de nouvelles descriptions, réduisant la lacune restante aux colonnes qui nécessitent genuinement une attention.

Comparaison

Les deux sont des packages dbt que vous installez via packages.yml (codegen) ou pip (osmosis). Aucun des deux ne nécessite dbt Cloud — ils fonctionnent avec n’importe quel projet dbt Core.