This hub connects the notes on building, testing, and distributing dbt packages. A package is a dbt project structured for reuse, using var(), dispatch, and namespacing to make it installable by anyone.
The Building Blocks
Understanding the Structure
- dbt Package Anatomy — What makes a package different from a project, the standard directory layout, and
dbt_project.ymlconfiguration for packages.
Making Models Reusable
- dbt Packageable Model Patterns — The three techniques that make models installable by anyone: configurable sources with
var(), enable/disable flags, and namespaced model names. - dbt Macros — Dispatch pattern for cross-database compatibility, Jinja fundamentals, and macro best practices. Essential for packages that support multiple warehouses.
Testing
- dbt Package Integration Testing — The
integration_tests/sub-project pattern used by Fivetran and dbt Labs to verify packages produce correct results. - dbt Package CI/CD — Matrix testing across warehouses and dbt versions with GitHub Actions.
Distribution
- dbt Hub Publishing — The registration process, hubcap automation, transitive dependency resolution, and best practices for Hub packages.
- dbt Private Packages via Git — Git distribution for internal packages, version pinning, and authentication options.
Quality
- dbt Package Anti-Patterns — Six common mistakes: hardcoded schemas, missing dispatch, tight constraints, generic names, table defaults, and missing version bounds.
Decision Points
When to package at all: The same macro or model set has been copied across three projects, or SQL duplication across repos is creating maintenance problems.
Package vs Mesh: If you’re sharing reusable logic (macros, tests, model templates), build a package. If you’re sharing curated data products with defined contracts, use Mesh. See dbt Packages vs Mesh for the full framework.
Hub vs Git: Start with a Git package for internal use. Move to the Hub when the package is stable enough for the broader community. The Hub adds transitive dependency resolution and version range support.
The Path from Project to Package
Most packages start as code you’ve already battle-tested:
- Extract — Identify reusable macros, models, or tests in your existing project
- Configure — Replace hardcoded references with
var()calls (patterns) - Namespace — Prefix model names with the package name
- Port — Add dispatch implementations for target warehouses
- Test — Build an integration test suite
- Automate — Set up CI/CD across warehouses and versions
- Distribute — Share via Git or Hub
Related Resources
- dbt Three-Layer Architecture — The base/intermediate/mart pattern that packages follow internally
- dbt Project Structure and Naming — Naming conventions and directory layout (packages follow the same principles)
- dbt Testing Taxonomy — Generic tests, unit tests, and contracts that complement integration testing