Skip to main content
dbt™ v2 is the current major version of dbt™, delivered through the dbt Fusion engine. 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.
Prerequisites
  • Your project on dbt™ 1.12, upgraded via the 1.12 guide. Its opt-in --use-v2-parser flag is the low-risk way to test v2 compatibility.
  • An Admin role in Paradime if you’ll be changing workspace or environment versions while testing.
Estimated time: varies with project size; the DinoAI upgrade agent or dbt-autofix automates most of it.
In Paradime, dbt™ v2 is the 2.0-latest version, which runs the dbt Fusion engine. When it’s available for your workspace, you can switch the whole workspace in Settings > General under Change version, or one Bolt environment in its Environment settings. Prepare your project against 1.12 with the v2 parser first.

​
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. It no longer writes target/catalog.json (see Artifacts in Paradime).
  • dbt freshness checks every source and model with freshness configured, in one command, and writes target/freshness.json. dbt source freshness still works and checks sources only.
  • 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).

​
Artifacts in Paradime

Paradime reads the artifacts your dbt™ commands write, so a few v2 changes affect what you run in Bolt.

​
catalog.json needs --write-catalog

On v2, dbt docs generate no longer writes target/catalog.json. To write it, add --write-catalog to dbt build, dbt run, dbt compile, or dbt parse:
Paradime’s own catalog refresh already does this on v2, so the Paradime catalog needs no change from you. Add --write-catalog to a Bolt schedule only when something reads that schedule’s catalog.json, such as a schedule that runs paradime run datahub-artifacts-push, which skips a project without a catalog.json.

​
Source and model freshness

dbt freshness writes target/freshness.json, covering sources and models, and also writes target/sources.json when sources are included. Bolt shows both kinds in the run’s source freshness results, with models grouped under models. A source_status: selection still reads sources.json, so keep sources in the dbt freshness command that feeds it: dbt freshness --resource-type model writes no sources.json. v2 writes freshness statuses as Pass, Warn, and Error, where v1 writes pass, warn, and error (dbt-labs/dbt#16400). Paradime normalizes them, but expect the capitalized form if you read sources.json yourself, for example through the Bolt API.
A sources.json written by one major version can’t be read as --state by the other. v2 ignores a v1 file, so source_status:fresher+ selects nothing, and v1 fails on a v2 file. After you switch versions, the first Bolt run that defers to a run from the old version is affected; the run after it reads a file the new version wrote.

​
Semantic models and metrics

v2 doesn’t write semantic models or metrics defined in the legacy semantic layer YAML to manifest.json; it logs SemanticModelDeprecated (dbt1157) instead. Until you migrate them to the YAML that warning asks for, they don’t appear in the Paradime catalog.

​
Run results

A model, seed, or snapshot that builds but logs a warning reports warn in run_results.json, where v1 reported success. Paradime State and the Discovery API count it as a success, so lastRunStatus reads success. Run details still shows the node with a warning status. If your own tooling reads run_results.json and expects only success, error, or skipped for these nodes, update it.

​
Distributions

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

​
Readiness steps

1

Resolve every deprecation warning

On dbt™ 1.12 in the Code IDE, run dbt parse and clear all deprecation warnings, including the 1.10 and 1.11 waves. Use dbt-autofix or the DinoAI upgrade agent to automate the mechanical fixes.
2

Parse with the v2 parser

Run dbt parse --use-v2-parser and fix anything it reports. A clean v2 parse on 1.12 is the strongest signal your project is v2-ready.
3

Update commands and scripts

Sweep Bolt schedule commands, schedules as code, and CI configuration for -m / --models, --resource-type, and partial-parse flags, and replace them with the v2-compatible forms.
4

Check package compatibility

Confirm each package’s require-dbt-version covers 2.0.0 or carries the Fusion-compatible badge on the package hub, and plan upgrades for the rest.
5

Write catalog.json where it's read

For each Bolt schedule whose catalog.json something reads, such as one that runs paradime run datahub-artifacts-push, add --write-catalog to one of its dbt commands.
dbt parse --use-v2-parser completes with no errors or deprecation warnings, and no Bolt schedule uses a removed CLI flag. The most common leftovers are custom properties still outside config.meta and -m flags in old schedule commands.

​
Next steps

Upgrade with the DinoAI agent

Automate the whole readiness checklist as one reviewed PR.

Manage dbt™ version

The workspace setting where new versions appear.

Official v2 upgrade guide

The upstream dbt™ documentation this guide is based on, including the full deprecated-flags table.

dbt™ changes overview

dbt Labs’ comparison of deprecations, behavior flags, and removed CLI flags.