dbt Packages & Tests
Independent cookbook

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.