dbt deps et le fichier de verrouillage des packages

dbt deps résout et installe les dépendances de packages. Il existe deux fichiers de configuration pour déclarer ces dépendances — packages.yml et dependencies.yml — et ils se comportent différemment de façons qui affectent les packages privés et les configurations Mesh. Le fichier de verrouillage produit par dbt deps contrôle la reproductibilité.

Deux fichiers de configuration, deux objectifs différents

packages.yml

Le lieu traditionnel pour déclarer les dépendances de packages. Il supporte le rendu Jinja, ce qui signifie que vous pouvez utiliser env_var() pour injecter des tokens pour les dépôts privés :

packages:
  - git: "https://{{ env_var('GIT_TOKEN') }}@github.com/my-org/private-package.git"
    revision: v1.2.0
  - package: dbt-labs/dbt_utils
    version: [">=1.0.0", "<2.0.0"]

Si vous travaillez avec des packages privés nécessitant des tokens d’authentification, c’est ici qu’ils doivent figurer.

dependencies.yml

Introduit pour dbt Mesh, ce fichier consolide deux choses en un seul endroit : les dépendances de packages et les références inter-projets. Vous déclarez quels autres projets dbt Cloud votre projet référence via ref() :

packages:
  - package: dbt-labs/dbt_utils
    version: [">=1.0.0", "<2.0.0"]

projects:
  - name: finance
    dbt_cloud:
      project_id: 12345

Le piège : dependencies.yml ne supporte pas le rendu Jinja. Pas de env_var(). Si vos packages nécessitent des tokens d’authentification injectés au moment de l’installation, ils doivent rester dans packages.yml.

La règle pratique : utilisez packages.yml pour les packages quand vous avez des dépôts privés. Utilisez dependencies.yml quand vous êtes dans une configuration Mesh et souhaitez que les références inter-projets coexistent avec vos déclarations de packages. Pour la plupart des projets sans Mesh, ils sont interchangeables — choisissez-en un et tenez-vous-y.

Ce qui se passe quand vous exécutez dbt deps

dbt deps fait trois choses en séquence :

Lit toutes les déclarations de packages depuis packages.yml et/ou dependencies.yml
Résout le graphe de dépendances — si le package A nécessite dbt-utils >=1.0.0 et le package B nécessite dbt-utils >=1.1.0, il trouve la version satisfaisant toutes les contraintes
Installe les packages résolus dans un répertoire dbt_packages/ à la racine du projet

Les packages installés sont des projets dbt entièrement fonctionnels. Leurs macros, modèles, tests et seeds deviennent disponibles pour votre projet exactement comme si vous les aviez écrits vous-même. Quand vous exécutez dbt compile, dbt traite à la fois votre projet et tous les packages installés comme un projet combiné unique.

Le fichier de verrouillage

Depuis dbt 1.7, dbt deps écrit automatiquement un fichier package-lock.yml enregistrant les versions exactes résolues, y compris les SHAs de commit Git pour les packages Git :

packages:
  - package: dbt-labs/dbt_utils
    version: 1.3.0
    install_git: https://github.com/dbt-labs/dbt-utils.git
    commit: abc123def456...
  - git: https://github.com/my-org/internal-utils.git
    revision: v0.4.0
    commit: 789ghi...

Commitez ce fichier dans le contrôle de version. Le fichier de verrouillage est ce qui rend dbt deps reproductible — sans lui, deux développeurs exécutant dbt deps à des moments différents pourraient obtenir des versions différentes si une nouvelle release est sortie. Avec le fichier de verrouillage, tout le monde obtient des installations identiques. Votre pipeline CI obtient également des installations identiques à celles que vous avez testées en local.

Si vous souhaitez que tout le monde reconstruise à partir des contraintes de version déclarées (en ignorant les versions verrouillées), utilisez dbt deps --upgrade. Cela force une résolution fraîche et écrit un nouveau fichier de verrouillage.

Flags utiles

Quelques flags qui modifient le comportement de dbt deps :

dbt deps --upgrade Force la résolution from scratch, en ignorant le fichier de verrouillage existant. À utiliser quand vous souhaitez récupérer de nouvelles versions de packages et mettre à jour le fichier de verrouillage.

dbt deps --lock Met à jour le fichier de verrouillage en fonction des déclarations actuelles sans réellement installer quoi que ce soit dans dbt_packages/. Utile pour vérifier ce qui serait résolu avant l’installation, ou pour mettre à jour le fichier de verrouillage en CI sans déclencher une installation complète.

dbt deps --add-package Ajoute un nouveau package depuis la CLI sans modifier manuellement votre fichier de configuration. Supporte --source hub, --source git ou --source local :

dbt deps --add-package dbt-labs/dbt_utils@1.3.0 --source hub

Cela écrit l’entrée dans packages.yml et exécute le cycle de résolution complet.

Le répertoire dbt_packages/

Les packages installés résident dans dbt_packages/ à la racine de votre projet. Ce répertoire doit être dans le gitignore — c’est du résultat généré, pas du code source. Toute personne clonant votre dépôt exécute dbt deps pour le recréer.

Le répertoire est plat : chaque package obtient son propre sous-répertoire portant le nom du package. Si vous déboguez une macro qui ne se comporte pas comme prévu, vous pouvez lire directement la source installée :

dbt_packages/
├── dbt_utils/
│   └── macros/
│       └── sql/
│           └── generate_surrogate_key.sql
├── dbt_expectations/
└── fivetran_utils/

La source du package que vous lisez est le code exact qui s’exécute quand votre projet compile. Si une macro fait quelque chose d’inattendu, la lire directement est plus rapide que lire le dépôt GitHub, qui peut être sur une version différente.

Ce que dbt deps ne fait pas pour les packages Git

Une limitation importante : dbt deps résout automatiquement les conflits de versions pour les packages Hub mais pas pour les packages Git. Si deux de vos packages Hub dépendent tous deux de dbt-utils, dbt trouve une version qui satisfait les deux. Si l’un de vos packages est une dépendance Git qui dépend également de dbt-utils, vous devez vérifier manuellement la compatibilité des versions.

C’est la principale raison de préférer les packages Hub aux packages Git lors de la publication de packages open source — les utilisateurs bénéficient d’une déduplication automatique. Pour les packages internes où vous contrôlez tous les consommateurs, Git convient. Pour les packages utilisés par des personnes que vous ne connaissez pas, la distribution via Hub rend leur vie significativement plus facile.