Prepare for dbt™ v2

dbt™ v2 is the next major version of dbt™, delivered through the dbt Fusion engine (in beta at the time of writing). It is faster and stricter: your project language and DAG semantics carry over, but v2 removes deprecated functionality and validates inputs rigorously, so a 1.x project needs preparation before it parses on v2. This guide covers that preparation, which you can do today from dbt™ 1.12 in Paradime. It is based on the official dbt™ upgrade guide for v2.

​

A clean slate

v2 does not support deprecated functionality:

• All deprecation warnings must be resolved before upgrading, including historic deprecations and the ones introduced in dbt™ 1.10: custom properties outside meta, duplicate YAML keys, orphaned Jinja blocks, and properties that moved to configs.
• Some behavior change flags are removed (generally in their enabled state). You can no longer opt out of them with flags: in dbt_project.yml.

Much of this is auto-fixable with the dbt-autofix helper or the dbt Labs migration agent skill.

​

Ecosystem packages

The most popular dbt-labs packages (dbt_utils, audit_helper, dbt_external_tables, dbt_project_evaluator) are already v2-compatible. External packages may use outdated code that fails to parse on v2. To check a package, look for the Fusion-compatible badge on the dbt™ package hub or review its require-dbt-version: a range that equals or contains 2.0.0 (for example ">=1.10.0,<3.0.0") is compatible. Test packages that aren’t clearly compatible before deploying.

​

Changed functionality in v2

These are the specific behavior changes to expect when your project moves to v2.

​

Errors move from compile time to parse time

In v1, dbt parse passes and only dbt compile fails on a nonexistent macro or adapter method ({{ my_nonexistent_macro('amount') }}, {{ adapter.does_not_exist() }}), an undefined generic test in YAML, or a missing variable ({{ var('does_not_exist') }}). In v2, all of these fail at dbt parse.

​

CLI flags that need changes

• --models / --model / -m: use --select / -s instead (renamed back in dbt™ 0.21). v2 raises an error if you use the old flags. Update Bolt schedule commands that still use them.
• --resource-type / --exclude-resource-type: use --resource-types / --exclude-resource-types.
• --partial-parse / --no-partial-parse: no longer supported; remove them from commands (v2 logs deprecation warning dbt1700 if passed).

A longer list of historic v1 flags (such as --print, --printer-width, --cache-selected-only, --static-parser) becomes inert in v2: passing them doesn’t error, the flag just does nothing and warns. See the deprecated flags table.

​

Stricter validation

• Duplicate docs blocks with the same name (for example, identical block names across two packages) now error instead of silently picking one. Rename the duplicates.
• Package version conflicts: if a local package depends on a hub package the root project also requires at a different version, dbt deps errors (Cannot combine non-exact versions) instead of installing whatever the root requests.
• Standalone YAML anchors at the top level of a properties file error; move them under the anchors: key as described in the 1.10 guide.
• Algebraic operations around return() in macros (for example return('xyz') + 'abc') are no longer supported; the surrounding expression is ignored with a JinjaTopLevelReturn warning. Compute the value inside return().

​

Runtime behavior changes

• dbt build runs all unit tests first, then builds the rest of the DAG, thanks to built-in column name and type awareness. In v1, unit tests ran in lineage order and needed the model’s direct parents to exist in the warehouse.
• dbt compile keeps going after an error: v2 skips nodes downstream of a failed compile but continues compiling the rest of the DAG in parallel, where v1 stopped at the first error.
• Threads are managed automatically on Snowflake and Databricks (the threads setting acts as a maximum cap if set); on BigQuery and Redshift, v2 respects user-set threads, and --threads 0 or omitting the setting enables dynamic optimization. v1 defaulted to --threads 1.
• dbt clean is contained: it no longer deletes files in configured resource paths or outside the project directory.
• Seeds with trailing commas no longer produce a spurious extra empty column.
• Parse-time printing of get_relation() outputs the fully qualified relation name instead of None, because v2 resolves relation names at parse time to batch get_relation() calls and speed up dbt compile.
• Custom configs require meta accessors: config.get() and config.require() no longer return values that exist only under meta; config.get() returns the default with a warning and config.require() errors. Use config.meta_get('my_key') and config.meta_require('my_key') instead.

​

New functionality

• dbt login enables browser-based authentication against the dbt platform and unlocks features such as the advanced dbt VS Code extension capabilities; dbt login status shows your authentication state.
• dbt Docs v2: dbt docs generate compiles the project, produces Parquet artifacts, and exports a static site in one command; the browser queries the artifacts directly with DuckDB-WASM, so the output can be hosted on any static file host.
• Snowflake ML model functions are supported with simplified type checking: any arguments are accepted, and results are treated as VARIANT, so cast them to the expected type (for example my_model!predict(input_column)::float).

​

Distributions

v2 is available in two distributions: the dbt package (the dbt Fusion engine, the recommended v2 experience) and dbt-core 2.0 (the Apache 2.0 open-source runtime) for organizations with a strict open-source requirement. Projects not ready for v2 can continue on dbt Core™ 1.x. See dbt™ licensing.

​

Readiness steps

​

Next steps