dbt Packages & Tests
Which package, test, or incremental strategy to use — and the failures that show up in a real run.
This is a small, independent cookbook for recurring dbt decisions: incremental strategies, which tests to start with, dbt_utils, package pinning, custom tests, snapshots, unit tests, and model contracts.
It is not a second dbt Package Hub and not a substitute for dbt documentation. Official docs are linked on every page.
Examples in the companion project under examples/cookbook/ were run with dbt-core 1.12.7 and dbt-duckdb 1.11.1, using dbt_utils 1.4.1. Adapter-specific behavior for Snowflake or Databricks is labeled as documentation-only and was not executed on those platforms.
Incremental strategies — merge, delete+insert, append
Official adapter support, what each strategy does to existing rows, and a merge that failed until the source was unique.
unique_key, predicates, and date-window increments
Why merge without a unique_key appends, why a date window is not a key, and how incremental_predicates are documented on Snowflake.
Which data tests to start with
Built-in generic tests, the data_tests YAML key, singular tests, and a relationships test that caught an orphan order.
dbt_utils workhorses
generate_surrogate_key in a real run, unique_combination_of_columns, and why the old surrogate_key name still trips people up.
accepted_values, severity, and source freshness
A passing accepted_values test, when to use warn instead of fail, and how official source freshness is configured.
Pinning packages in 2026
How to depend on dbt packages, why unpinned git installs warn, and which well-known packages need a second look.
Custom generic and singular data tests
A parameterized test block that ran in the companion project, versus a one-off SQL file of failing rows.
Snapshots for SCD type 2
YAML snapshots in dbt 1.9+, a successful first snapshot, and why unique_key quality decides whether dbt_scd_id helps you.
Unit tests and seed type inference
A unit test that failed when 10.50 was cast to INTEGER 11, then passed after seed column types were declared.
Model contracts
An enforced contract that ran successfully, and why contracts are not a substitute for data tests.