Il existe trois façons d’installer un package dbt : depuis le Hub, depuis un dépôt Git, ou depuis un chemin filesystem local. Chacune présente des compromis distincts. La plupart des équipes utilisent les trois à un moment ou un autre — Hub pour les packages open-source, Git pour les bibliothèques internes, local pour le développement et les tests.
Packages Hub
Les packages Hub s’installent depuis hub.getdbt.com en utilisant des plages de versions sémantiques :
packages: - package: dbt-labs/dbt_utils version: [">=1.0.0", "<2.0.0"] - package: metaplane/dbt_expectations version: [">=0.10.0", "<1.0.0"]Le namespace est {éditeur}/{nom_package}. La plage de versions permet à dbt de choisir la meilleure version compatible plutôt que de se verrouiller sur une release spécifique.
L’avantage clé : résolution automatique des dépendances transitives. Si dbt_expectations et fivetran/ad_reporting dépendent tous deux de dbt_utils, le Hub réconcilie leurs exigences de version automatiquement. Il trouve la version la plus haute satisfaisant toutes les contraintes et en installe exactement une copie. C’est ce qui rend les grands écosystèmes de packages gérables.
Utilisez les packages Hub chaque fois que le package y est disponible publiquement. La déduplication seule le justifie.
Packages Git
Les packages Git s’installent depuis n’importe quel dépôt Git, épinglés à un tag, une branche ou un SHA de commit :
packages: - git: "https://github.com/my-org/internal-utils.git" revision: v0.4.0Pour les dépôts privés, utilisez la clé private avec l’authentification native du fournisseur plutôt qu’intégrer des tokens :
packages: - private: my-org/internal-utils provider: github revision: v0.4.0L’approche private + provider utilise les credentials Git déjà configurés dans votre environnement (GitHub App, deploy key, clé SSH) plutôt qu’incorporer un token dans votre fichier de configuration. Voir Packages dbt privés via Git pour les options d’authentification complètes.
La limitation clé : pas de résolution des dépendances transitives. Si votre package Git dépend de dbt-utils et que le projet de l’utilisateur déclare aussi dbt-utils avec une plage de versions incompatible, vous obtenez une erreur de résolution. Vous devez aligner manuellement les versions sur tous vos packages Git.
C’est gérable lorsque vous contrôlez les deux côtés (packages internes partagés entre vos propres projets). Cela devient douloureux si vous distribuez un package à de nombreux utilisateurs — ils rencontreront des conflits de versions et devront les déboguer manuellement. Si un package est prêt pour une utilisation plus large, le publier sur le Hub vaut l’effort.
Packages locaux
Les packages locaux s’installent depuis des chemins filesystem via des liens symboliques :
packages: - local: ../my-local-packageLe chemin est relatif à la racine de votre projet. Cela crée un lien symbolique dans dbt_packages/, de sorte que les modifications du package local sont immédiatement reflétées sans ré-exécuter dbt deps.
Les packages locaux sont spécifiquement utiles pour :
- Développement en monorepo — plusieurs projets dbt dans un seul dépôt, référençant des packages partagés depuis des répertoires frères
- Développement de packages — tester votre package contre un vrai projet avant de le publier. Le pattern du sous-projet
integration_tests/utilisé par Fivetran et dbt Labs référence le package parent vialocal: ../exactement de cette façon.
N’utilisez pas les packages locaux en production. Si votre pipeline CI résout un chemin local, le package ne sera pas présent sur le runner CI. Local est pour le développement, pas le déploiement.
Choisir entre eux
| Situation | Utiliser |
|---|---|
| Le package est sur le Hub | Hub |
| Package interne, dépôt privé | Git avec private + provider |
| Développer ou tester un package localement | Local |
| Package externe pas encore sur le Hub | Git |
| Contribuer à un package avant sa publication | Local |
La progression typique pour un nouveau package interne : local pendant le développement → Git une fois suffisamment stable pour partager avec votre équipe → Hub une fois prêt pour la communauté plus large.
Patterns de conflits de versions et comment les éviter
L’erreur la plus courante que les nouveaux utilisateurs dbt rencontrent est un conflit de versions qui ressemble à ceci :
Could not find a compatible version for package dbt-labs/dbt_utilsCela arrive quand deux packages déclarent des exigences incompatibles de version pour une dépendance partagée. La correction est presque toujours la même : supprimer la dépendance partagée de votre packages.yml racine.
Voici l’erreur :
# packages.yml - ceci cause des problèmespackages: - package: dbt-labs/dbt_utils version: [">=1.1.0", "<1.2.0"] # épinglé trop strictement - package: fivetran/ad_reporting version: [">=2.0.0", "<3.0.0"] # requiert aussi dbt-utils >=1.0.0, <2.0.0La plage >=1.1.0, <1.2.0 est trop étroite. Quand ad_reporting inclut aussi dbt-utils avec une plage plus large, dbt doit satisfaire les deux contraintes simultanément, ce qui peut être impossible si la dernière version dbt-utils dépasse 1.2.0.
La correction : ne listez que les packages que vous utilisez directement dans vos modèles. Ne listez pas leurs dépendances transitives.
# packages.yml - correctpackages: - package: fivetran/ad_reporting version: [">=2.0.0", "<3.0.0"]# dbt_utils est installé automatiquement comme dépendance transitive de ad_reportingSi vous avez réellement besoin d’utiliser des macros dbt-utils dans votre propre code, ajoutez-les avec une plage large :
packages: - package: dbt-labs/dbt_utils version: [">=1.0.0", "<2.0.0"] # plage large, pas épinglée strictement - package: fivetran/ad_reporting version: [">=2.0.0", "<3.0.0"]Fivetran avertit explicitement à ce sujet dans leurs READMEs de packages, ce qui montre à quel point c’est fréquent. L’anti-pattern piège des ingénieurs expérimentés qui savent que leur projet « a besoin » de dbt-utils et l’ajoutent explicitement sans réaliser qu’un package en aval l’importe déjà.
Le même principe s’applique aux bundles : lors de l’installation d’un bundle cross-platform comme fivetran/ad_reporting, n’installez pas également les packages de plateformes individuelles comme fivetran/google_ads ou fivetran/facebook_ads. Le bundle les installe comme dépendances. Les installer séparément crée le même pattern de conflit.