Upgrading to v2.0
dbt Core v2.0 is currently in alpha. This does not affect the Fusion in platform rollout, which continues on its existing track.
v2.0 marks a new foundation for dbt: a faster, Rust-based runtime, rebuilt from the ground up and available in two distributions. For most users, the right choice is Fusion, which extends the open-source core with SQL comprehension, column-level lineage, instant feedback, and platform-connected workflows.
For license-aware customers, we offer dbt Core v2.0, a distribution that includes only Apache 2.0 open-source code. Both distributions share the same project language and DAG semantics, so once you upgrade to v2.0, your existing dbt project works with either distribution.
The dbt Fusion engine is currently available for installation in:
- Local command line interface (CLI) tools Preview
- VS Code and Cursor with the dbt extension Preview
- dbt platform environments
Join the conversation in our Community Slack channel #dbt-fusion-engine.
Read the Fusion Diaries for the latest updates.
More information about Fusion
Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations:
- About the dbt Fusion engine
- About the dbt extension
- New concepts in Fusion
- Supported features matrix
- Installing Fusion CLI
- Installing VS Code extension
- Fusion release track
- Quickstart for Fusion
- Upgrade guide
- Fusion license agreement
Distributions
Two dbt distributions build on the Fusion runtime:
| Loading table... |
Installation
For most users, the recommended path is to install Fusion as it includes all of dbt Core v2.0 plus the robust Fusion feature set.
Fusion
Install Fusion using pip, or see all installation options (brew, winget, CDN):
python -m pip install --pre dbt
dbt Core v2.0
If you specifically need the open-source distribution of v2, install dbt Core. During alpha, you must target either the pre-release version or an explicit pin. You can copy the following commands to install the alpha and immediately update to the most recent version:
Pre-release version:
python -m pip install --pre dbt-core
Explicit pin:
python -m pip install dbt-core==2.0.0-alpha.1
What to know before upgrading
This new major version is an opportunity to strengthen the framework by removing deprecated functionality, rationalizing confusing behavior, and providing more rigorous validation on erroneous inputs. This means that there is some work involved in preparing an existing dbt project for v2.
That work is documented below — it should be simple, straightforward, and in many cases, auto-fixable with the dbt-autofix helper or the agent skill.
If you're on dbt Core v1.12, you can test Fusion parser compatibility before fully migrating by using the opt-in --use-v2-parser flag. This delegates parsing to the Fusion parser without changing any other behavior, making it a low-risk way to catch compatibility issues early.
Upgrade considerations
Keep in mind the following considerations during the upgrade process:
-
Manifest incompatibility — Fusion is backwards-compatible and can read dbt Core manifests. However, dbt Core isn't forward-compatible and can't read Fusion manifests. Fusion produces a
v20manifest, while the latest version of dbt Core still produces av12manifest.As a result, mixing dbt Core and Fusion manifests across environments breaks cross-environment features. To avoid this, use
state:modified,--defer, and cross-environmentdbt docs generateonly after all environments are running the latest Fusion version. Using these features before all environments are on Fusion may cause errors and failures. -
State-aware orchestration — If using state-aware orchestration, dbt doesn't detect a change if a table or view is dropped outside of dbt, as the cache is unique to each dbt platform environment. This means state-aware orchestration will not rebuild that model until either there is new data or a change in the code that the model uses.
- Workarounds:
- Use the Clear cache button on the target Environment page to force a full rebuild (acts like a reset), or
- Temporarily disable state-aware orchestration for the job and rerun it.
State-aware orchestration is now dbt Statedbt State works with all engines and environments: dbt Core, the dbt platform, and dbt Fusion engine.
If you're using state-aware orchestration prior to June 1, 2026, you can continue using it. Existing state-aware orchestration customers automatically receive a 90-day trial of dbt State. To get started, refer to Migrate from state-aware orchestration.
- Workarounds:
Supported adapters
The following adapters are supported in v2.0:
A clean slate
v2 will not support any deprecated functionality (see the Changes overview for details):
- All deprecation warnings must be resolved before upgrading to the new engine. This includes historic deprecations and new ones as of dbt Core v1.10.
- Some behavior change flags will be removed (generally enabled). You can no longer opt out of them using
flags:in yourdbt_project.yml.
Ecosystem packages
The most popular dbt-labs packages (dbt_utils, audit_helper, dbt_external_tables, dbt_project_evaluator) are already compatible with Fusion. External packages published by organizations outside of dbt may use outdated code or incompatible features that fail to parse with the new Fusion engine. We're working with those package maintainers to make packages available for Fusion. Packages requiring an upgrade to a new release for Fusion compatibility, will be documented in this upgrade guide.
New and changed features and functionality
Changed functionality
When developing v2, there were opportunities to improve the dbt framework — failing earlier (when possible), fixing bugs, optimizing run order, and deprecating flags that are no longer relevant. The result is a handful of specific and nuanced changes to existing behavior.
When upgrading to v2, you should expect the following changes in functionality:
Parse time printing of relations will print out the full qualified name, instead of an empty string
In dbt Core v1, when printing the result of get_relation(), the parse time output for that Jinja would print None (the undefined object coerces to the string "None").
In v2, to help with intelligent batching of get_relation() calls (and significantly speed up dbt compile), dbt needs to construct a relation object with the fully qualified name resolved at parse time for the get_relation() adapter call.
Constructing a relation object with the fully qualified name in v2 produces different behavior than v1 in print(), log(), or any Jinja macro that outputs to stdout or stderr at parse time.
Example:
{% set relation = adapter.get_relation(
database=db_name,
schema=db_schema,
identifier='a')
%}
{{ print('relation: ' ~ relation) }}
{% set relation_via_api = api.Relation.create(
database=db_name,
schema=db_schema,
identifier='a'
) %}
{{ print('relation_via_api: ' ~ relation_via_api) }}
The output after dbt parse in dbt Core v1:
relation: None
relation_via_api: my_db.my_schema.my_table
The output after dbt parse in v2:
relation: my_db.my_schema.my_table
relation_via_api: my_db.my_schema.my_table
Deprecated flags
Deprecated flags are command-line flags (like --models, --print) that you pass to dbt commands. These are being removed in v2. This is different from:
- Deprecation warnings — Features in your project code (models, YAML, macros) that need to be updated
- Behavior change flags — Flags in
dbt_project.ymlthat let you opt in/out of new behaviors
See the Changes overview for a full comparison.
Some historic CLI flags from v1 will no longer do anything in v2. If you pass them into a dbt command in v2, the command will not error, but the flag will do nothing (and warn accordingly).
| Loading table... |
CLI flags that need changes
The following deprecated flags require updates in your job definitions or scripts:
-
--models/--model/-m: Use--select/-sinstead (renamed in dbt Core v0.21). dbt raises an error in v2 if you use the old flags. Do not pass--modelsas the value to-s(for example,dbt run -s --models); v1 treated that as a model name, but v2 requires a valid selector. -
--resource-type/--exclude-resource-type: Use--resource-types/--exclude-resource-types. For more information, see Resource type flags.
Fusion job runs no longer support the --partial-parse and --no-partial-parse CLI flags. If you pass them (for example, from a dbt Core command or script), dbt logs deprecation warning dbt1700. Remove these flags from your Fusion job commands. For more information, refer to Deprecated flags in the guide to upgrading to the dbt Fusion engine.
Conflicting package versions when a local package depends on a hub package which the root package also wants will error
If a local package depends on a hub package that the root package also wants, dbt deps doesn't resolve conflicting versions in dbt Core v1; it will install whatever the root project requests.
Fusion will present an error:
error: dbt8999: Cannot combine non-exact versions: =0.8.3 and =1.1.1
Parse will fail on nonexistent macro invocations and adapter methods
When you call a nonexistent macro in dbt:
select
id as payment_id,
# my_nonexistent_macro is a macro that DOES NOT EXIST
{{ my_nonexistent_macro('amount') }} as amount_usd,
from app_data.payments
Or a nonexistent adapter method:
{{ adapter.does_not_exist() }}
In v1, dbt parse passes, but dbt compile fails.
In v2, dbt will error out during parse.
Parse will fail on missing generic test
When you have an undefined generic test in your project:
models:
- name: dim_wizards
data_tests:
- does_not_exist
In v1, dbt parse passes, but dbt compile fails.
In v2, dbt will error out during parse.
Parse will fail on missing variable
When you have an undefined variable in your project:
select {{ var('does_not_exist') }} as my_column
In v1, dbt parse passes, but dbt compile fails.
In v2, dbt will error out during parse.
Stricter evaluation of duplicate docs blocks
In v1, it was possible to create scenarios with duplicate docs blocks. For example, you can have two packages with identical docs blocks referenced by an unqualified name in your dbt project. In this case, v1 would use whichever docs block is referenced without any warnings or errors.
Fusion adds stricter evaluation of names of docs blocks to prevent such ambiguity. It will present an error if it detects duplicate names:
dbt found two docs with the same name: 'docs_block_title' in files: 'models/crm/_crm.md' and 'docs/crm/business_class_marketing.md'
To resolve this error, rename any duplicate docs blocks.
dbt clean will not delete any files in configured resource paths or files outside the project directory
In dbt Core v1, dbt clean deletes:
- Any files outside the project directory if
clean-targetsis configured with an absolute path or relative path containing../, though there is an opt-in config to disable this (--clean-project-files-only/--no-clean-project-files-only). - Any files in the
asset-pathsordoc-paths(even though other resource paths, likemodel-pathsandseed-paths, are restricted).
In v2, dbt clean will not delete any files in configured resource paths or files outside the project directory.
All unit tests are run first in dbt build
In dbt Core v1, the direct parents of the model being unit tested needed to exist in the warehouse to retrieve the needed column name and type information. dbt build runs the unit tests (and their dependent models) in lineage order.
In v2, dbt build runs all of the unit tests first, and then builds the rest of the DAG, due to built-in column name and type awareness.
Configuring --threads
dbt Core v1 runs with --threads 1 by default. You can increase this number to run more nodes in parallel on the remote data platform, up to the max parallelism enabled by the DAG.
v2 handles threading differently depending on your data platform:
| Loading table... |
For more information, refer to Using threads.
Continue to compile unrelated nodes after hitting a compile error
As soon as dbt Core v1 compile encounters an error compiling one of your models, dbt stops and doesn't compile anything else.
When Fusion's compile encounters an error, it will skip nodes downstream of the one that failed to compile, but it will keep compiling the rest of the DAG (in parallel, up to the number of configured / optimal threads).
Seeds with extra commas don't result in extra columns
In dbt Core v1, if you have an additional comma on your seed, dbt creates a seed with an additional empty column.
For example, the following seed file (with an extra comma):
animal,
dog,
cat,
bear,
Will produce this table when dbt seed is executed:
| Loading table... |
In v2, it will not produce this extra column in the table resulting from dbt seed:
| Loading table... |
Move standalone anchors under anchors: key
As part of the ongoing process of making the dbt authoring language more precise, unexpected top-level keys in a YAML file will result in errors. A common use case behind these unexpected keys is standalone anchor definitions at the top level of a YAML file. You can use the new top-level anchors: key as a container for these reusable configuration blocks.
For example, rather than using this configuration:
# id_column is not a valid name for a top-level key in the dbt authoring spec, and will raise an error
id_column: &id_column_alias
name: id
description: This is a unique identifier.
data_type: int
data_tests:
- not_null
- unique
models:
- name: my_first_model
columns:
- *id_column_alias
- name: unrelated_column_a
description: This column is not repeated in other models.
- name: my_second_model
columns:
- *id_column_alias
Move the anchor under the anchors: key instead:
anchors:
- &id_column_alias
name: id
description: This is a unique identifier.
data_type: int
data_tests:
- not_null
- unique
models:
- name: my_first_model
columns:
- *id_column_alias
- name: unrelated_column_a
description: This column is not repeated in other models
- name: my_second_model
columns:
- *id_column_alias
This move is only necessary for fragments defined outside of the main YAML structure. For more information about this new key, see anchors.
Algebraic operations in Jinja macros
In v1, you can set algebraic functions in the return function of a Jinja macro:
{% macro my_macro() %}
return('xyz') + 'abc'
{% endmacro %}
This is no longer supported in v2 and will emit a warning:
[warning] [JinjaTopLevelReturn (dbt1508)]: return is not at the top level of the block.
Its value is final and cannot be modified by surrounding expressions.
Example: return(0) + 1. The + 1 is ignored and the macro returns 0.
This is not a common use case and there is no deprecation warning for this behavior in v1. The supported format is:
{% macro my_macro() %}
return('xyzabc')
{% endmacro %}
Accessing custom configurations in meta
config.get() and config.require() don't return values from the meta dictionary. If you try to access a key that only exists in meta, dbt emits a warning:
warning: The key 'my_key' was not found using config.get('my_key'), but was
detected as a custom config under 'meta'. Please use config.meta_get('my_key')
or config.meta_require('my_key') instead.
Behavior when a key exists only in meta:
| Loading table... |
To access custom configurations stored under meta, use the explicit methods:
{% set owner = config.meta_get('owner') %}
{% set has_pii = config.meta_require('pii') %}
For more information, see config.meta_get() and config.meta_require().
Fusion compiler
Snowflake model functions
Fusion supports Snowflake ML model functions, which allow you to call machine learning models directly in SQL.
Because model function return types are flexible and defined by the underlying model, Fusion uses simplified type checking:
- Arguments: Fusion accepts any arguments without strict type validation.
- Return type: Fusion treats all model function results as
VARIANT.
To use the result in your models, cast it to the expected type:
select
my_model!predict(input_column)::float as prediction_score
from {{ ref('my_table') }}
Package support
To determine if a package is compatible with the dbt Fusion engine, visit the dbt package hub and look for the Fusion-compatible badge, or review the package's require-dbt-version configuration.
-
Packages with a
require-dbt-versionthat equals or contains2.0.0are compatible with Fusion. For example,require-dbt-version: ">=1.10.0,<3.0.0".Even if a package doesn't reflect compatibility in the package hub, it may still work with Fusion. Work with package maintainers to track updates, and thoroughly test packages that aren't clearly compatible before deploying.
-
Package maintainers who would like to make their package compatible with Fusion can refer to the Fusion package upgrade guide for instructions.
Fivetran package considerations:
- The Fivetran
sourceandtransformationpackages have been combined into a single package. - If you manually installed source packages like
fivetran/github_source, you need to ensurefivetran/githubis installed and deactivate the transformation models.
Package compatibility messages
dbt-autofix logsFusion warnings and dbt-autofix logs may show different messages about package compatibility.
If you use dbt-autofix while upgrading to Fusion in the Studio IDE or dbt VS Code extension, you may see different messages about package compatibility between dbt-autofix and Fusion warnings.
Here's why:
- Fusion warnings are emitted based on a package's
require-dbt-versionand whetherrequire-dbt-versioncontains2.0.0. - Some packages are already Fusion-compatible even though package maintainers haven't yet updated
require-dbt-version. dbt-autofixknows about these compatible packages and will not try to upgrade a package that it knows is already compatible.
This means that even if you see a Fusion warning for a package that dbt-autofix identifies as compatible, you don't need to change the package.
The message discrepancy is temporary while we implement and roll out dbt-autofix's enhanced compatibility detection to Fusion warnings.
Here's an example of a Fusion warning in the Studio IDE that says a package isn't compatible with Fusion but dbt-autofix indicates it is compatible:
dbt1065: Package 'dbt_utils' requires dbt version [>=1.30,<2.0.0], but current version is 2.0.0-preview.72. This package may not be compatible with your dbt version. dbt(1065) [Ln 1, Col 1]
Was this page helpful?
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.
