dbt / Advanced: evidence, isolation and recoverable releases / Lesson 18

Release migration and product boundaries

Review v1.12 assumptions, current v2 naming and optional services without equating project syntax with feature entitlement.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish engine, distribution, adapter, package and hosted release context.
Plan semantic, artifact and data recovery checks across a release.

Use the names verified at the review date

Official documentation reviewed on 2026-10-28 calls the Python 1.x generation dbt v1, historically dbt Core 1.x. The Rust-based generation is dbt v2, formerly described as Fusion, and the Apache-only distribution is called dbt OSS. Hosted platform services, accounts and release tracks are another dimension. The course’s concrete syntax baseline remains v1.12; it does not imply v2 capabilities are absent, experimental or automatically included in v1. Verify present distribution terms and feature availability independently. Old posts about Fusion licensing or beta status should not be generalized to the current product without checking newer official sources.

A release changes more than the executable version

Review adapter interface support, package dependencies, behavior flags, YAML contexts, generated SQL and artifact readers. v2’s stricter language validation can reveal previously ignored settings, and file-type Jinja support differs between generations. A project that parses is not necessarily runtime-compatible on its target. The local checklist names a synthetic v1.12-to-v2.0 review but performs no upgrade. Test exact used paths and preserve rollback data semantics rather than assuming a framework major change is merely a faster implementation of every old workflow. Keep unresolved source or sink limitations visible.

json Illustrative technical example; logical results are reasoned, not engine-tested.

{"scope":"synthetic migration review","source_generation":"dbt v1.12","destination_generation":"dbt v2.0","verify":["adapter support","package paths","YAML contexts","generated SQL","artifact schemas","incremental and snapshot recovery"]}

A local release checklist, not a supported-version assertion for an actual adapter or an executed migration.

A centralized metric still needs a correct fact model

A governed open-loan metric is a stock at a defined observation time, while loans_started is a flow over a borrowing interval. Summing daily stock snapshots does not produce the number of unique loans. A semantic model must specify entities, grain, time and aggregation rules before a service can query it consistently. The local metric contract below is conceptual, not native MetricFlow YAML. Central definitions cannot repair duplicate fact rows or missing source branches. Keep metric meaning and acceptance examples alongside whichever supported semantic specification the deployment actually uses.

json Illustrative technical example; logical results are reasoned, not engine-tested.

{"metric":"open_loans","kind":"stock","entity":"loan_id","grain":"one validated loan lifecycle","time":"explicit observation timestamp","aggregation":"count eligible open loans, not sum daily stocks"}

A local business-metric model only. It creates no semantic model, service, metric endpoint or entitlement.

Project metadata and hosted services have separate availability

MetricFlow and semantic metadata are not identical to every hosted Semantic Layer API or integration. Likewise, ordinary state selectors and defer are different from the dbt State service that can reuse or clone resources under its own product rules. Feature badges, login requirements, subscription and supported adapters must be checked for the exact offering. Do not infer a paid service is enabled because a YAML key parses, or that every local capability is a hosted-only feature. This lesson provides no pricing estimate, subscription purchase or external service call; it explains the boundary so implementations can be reviewed accurately.

Accept a release with code, data and recovery evidence

A complete review reconciles source scope, selected resources, required tests, incremental transitions, snapshot history, runtime permissions and published outputs. Preserve exact engine, adapter, package and artifact versions with the accepted result. A code rollback cannot automatically undo changed historical keys or reconstruct discarded source versions. Rehearse the supported recovery path in an independent authorized environment before operational use. This course runs no upgrade, package install, build, semantic query or cloud operation. Validation is limited to local graph, fixture, CSV, JSON and delimiter models, with all dbt-specific fragments explicitly non-runnable.

Common errors and fixes

An old Fusion label is used to infer current license or beta status

Why it happens: Historical product terminology was treated as current entitlement evidence.
How to fix it: Check dated official distribution and feature documentation.
Prevent it next time: Record review date and exact generation in release notes.

Daily open-loan stocks are summed as unique loans

Why it happens: Stock and flow semantics were conflated.
How to fix it: Define the observation time, entity and appropriate aggregation.
Prevent it next time: Test metric definitions with small repeated-day examples.

A parsed semantic configuration is treated as an active hosted API

Why it happens: Metadata validity was confused with service setup and subscription availability.
How to fix it: Verify the actual service, adapter, credentials and entitlement separately.
Prevent it next time: Keep local framework and hosted-service claims distinct.

Check your understanding

1. Does summing10 open loans on Monday and10 on Tuesday prove20 unique loans?

Show worked solution

No. The same ten loans may be open on both days. Define whether the question asks stock at a time, loan-days or distinct loan identities over a period. A semantic service can only apply the chosen metric contract; it cannot infer the missing business definition.

2. What does a successful v1.12 project parse establish about v2 migration?