ServicesÀ proposNotesContact Me contacter →
EN FR
Note

Publication sur le dbt Hub

Comment publier un package dbt sur le dbt Hub — prérequis, processus d'enregistrement, automatisation avec hubcap et bonnes pratiques pour la gestion des versions.

Planté
dbtdata engineering

Le dbt Hub est le canal de distribution standard pour les packages dbt open source — un registre, pas une plateforme d’hébergement. Les packages vivent sur GitHub ; le Hub indexe leurs releases. Au début 2026, l’écosystème compte plus de 400 packages couvrant les transformations spécifiques aux sources (packages Fivetran), les utilitaires transversaux (dbt-utils, dbt-expectations) et les outils de monitoring (Elementary).

Prérequis

La publication sur le Hub nécessite trois choses :

  1. Le package est hébergé dans un dépôt GitHub public
  2. Il contient un dbt_project.yml avec un champ name
  3. Les releases utilisent des tags de versionnage sémantique (ex. v0.1.0)

C’est tout. Pas de métadonnées spéciales, pas de manifest séparé, pas de processus d’approbation au-delà de la PR initiale.

Le processus d’enregistrement

Faire apparaître votre première version sur le Hub est un processus en quatre étapes :

  1. Créez une release GitHub avec un tag semver. Les tags comme first-release, beta ou latest sont ignorés par l’indexeur du Hub. Utilisez v0.1.0, v1.0.0, etc.

  2. Ouvrez une pull request sur le dépôt hub.getdbt.com pour ajouter votre package à l’index. La PR ajoute votre dépôt à un manifest JSON.

  3. Attendez la revue. Les PRs sont généralement approuvées en un jour ouvré. L’équipe dbt Labs effectue une vérification de base — dbt_project.yml valide, tags semver, dépôt public.

  4. Mises à jour automatiques ensuite. Un script appelé hubcap s’exécute toutes les heures pour détecter automatiquement les nouvelles releases GitHub. Aucune autre PR n’est nécessaire pour les mises à jour de version.

Une fois enregistrées, les nouvelles releases sont récupérées par hubcap dans l’heure suivant la création d’une release GitHub. Le cycle devient : tagger une release, la pousser, et le Hub se met à jour automatiquement.

Comment les utilisateurs installent les packages du Hub

Une fois publié, les utilisateurs installent votre package avec une plage de version dans leur packages.yml :

packages.yml
packages:
  - package: your-namespace/my_package
    version: [">=0.1.0", "<1.0.0"]

L’espace de noms est généralement votre nom d’utilisateur ou d’organisation GitHub. La plage de version permet à dbt de résoudre automatiquement la meilleure version compatible.

L’avantage des dépendances transitives

Les packages du Hub ont un avantage significatif par rapport aux packages Git : la résolution automatique des dépendances transitives.

Si votre package dépend de dbt-utils et que le projet de l’utilisateur dépend également de dbt-utils, le Hub réconcilie automatiquement les conflits de version. Il choisit la version la plus haute qui satisfait toutes les contraintes. Les packages Git ne peuvent pas faire cela — les conflits de version entre dépendances Git nécessitent une résolution manuelle, et les messages d’erreur sont souvent cryptiques.

Cela importe en pratique car la plupart des packages non triviaux dépendent de dbt-utils. Quand un utilisateur a cinq packages installés et que les cinq dépendent de dbt-utils, le Hub trouve une version qui fonctionne pour tout le monde. Avec des dépendances Git, vous devriez assurer manuellement la compatibilité.

Bonnes pratiques

La documentation hubcap présente les pratiques que l’équipe dbt Labs a affinées en maintenant l’écosystème :

Définir require-dbt-version

require-dbt-version: [">=1.3.0", "<3.0.0"]

Les utilisateurs doivent connaître la compatibilité en amont. Sans cela, quelqu’un sur dbt 1.1 obtient des erreurs de compilation cryptiques au lieu d’un message clair « version incompatible ». Avec le moteur Fusion (dbt 2.0) désormais disponible, définir [">=1.3.0", "<3.0.0"] couvre les deux runtimes.

Déclarer les dépendances Hub quand c’est possible

Si votre package dépend de dbt-utils, référencez-le depuis le Hub, pas depuis Git :

# Bien — active la résolution transitive
packages:
  - package: dbt-labs/dbt_utils
    version: [">=1.0.0", "<2.0.0"]


# À éviter — casse la résolution transitive
packages:
  - git: "https://github.com/dbt-labs/dbt-utils.git"
    revision: v1.3.0

Les dépendances Hub participent à la résolution de version. Les dépendances Git non.

Utiliser des plages de version larges

N’épinglez pas à des versions patch. version: "1.3.0" force chaque utilisateur à utiliser exactement cette version et crée des conflits avec d’autres packages qui dépendent aussi de dbt-utils mais attendent un patch différent.

# Trop restrictif — crée des conflits de dépendances
- package: dbt-labs/dbt_utils
  version: "1.3.0"


# Mieux — permet la flexibilité
- package: dbt-labs/dbt_utils
  version: [">=1.0.0", "<2.0.0"]

Plus la plage qui fonctionne réellement est large, moins vos utilisateurs auront de problèmes.

Ne pas surcharger le comportement global

Votre package ne doit pas surcharger le comportement de dbt Core qui affecte les ressources en dehors de votre package. Surcharger generate_schema_name ou generate_alias_name dans un package change le comportement pour l’ensemble du projet de l’utilisateur, pas seulement pour vos modèles. Si vous avez besoin d’un comportement personnalisé, délimitez-le à vos propres modèles en utilisant le bloc config().

Préférer les macros cross-database intégrées

Depuis dbt-utils v1.0, les macros cross-database comme datediff, dateadd, safe_cast et hash se trouvent dans l’espace de noms dbt. Utilisez {{ dbt.datediff(...) }} plutôt que de réimplémenter vous-même l’arithmétique de dates. Cela réduit votre empreinte de dépendances et tire parti des implémentations spécifiques aux adaptateurs que dbt Core maintient.

Versionnage sémantique pour les packages

Suivez strictement le semver :

  • Patch (0.1.0 → 0.1.1) : Corrections de bugs uniquement. Pas de changement de comportement.
  • Minor (0.1.0 → 0.2.0) : Nouveaux modèles, nouvelles macros, nouvelles fonctionnalités. Comportement existant inchangé.
  • Major (0.2.0 → 1.0.0) : Changements incompatibles — modèles renommés, macros supprimées, schémas de sortie modifiés.

Les packages pré-1.0 (0.x.y) peuvent traiter les versions mineures comme des changements incompatibles, ce qui est courant pendant la phase de définition de la bonne API. Une fois passé à 1.0.0, vous vous engagez à la stabilité.

Maintenez un CHANGELOG.md qui documente ce qui a changé dans chaque version. Les utilisateurs doivent savoir si la mise à niveau de 0.3.0 à 0.4.0 est sûre ou nécessite des étapes de migration.

Quand ne pas utiliser le Hub

Tous les packages n’ont pas leur place sur le Hub. Les packages internes avec une logique métier propriétaire, les packages qui ne fonctionnent qu’avec les données d’une entreprise spécifique et les packages expérimentaux qui ne sont pas encore prêts pour la communauté sont mieux distribués en tant que packages Git. Le Hub est fait pour les packages qui résolvent un problème que la communauté au sens large partage.