How to Test Your dbt Project Before Upgrading to dbt v2

dbt v2 (the former Fusion engine) is now the default install. What changed, the new naming, the breaking changes that bite analytics projects, and a five-step way to test safely.

Divya NairDivya NairAuthor9 November 20265 min read 42 views
How to Test Your dbt Project Before Upgrading to dbt v2
In this article▾
  1. First, untangle the names
  2. What actually changes for your project
  3. A five-step way to test before you switch
  4. 1. Clear every deprecation warning on v1
  5. 2. Let dbt-autofix do the boring part
  6. 3. Try the v2 parser from inside v1.12
  7. 4. Check your adapter and packages
  8. 5. Run v2 in a separate environment and compare
  9. The DuckDB shortcut for local testing
  10. Common mistakes to avoid
  11. Should you upgrade now?

dbt v2 is out, and if you run pip install dbt today you get it. For an analyst who maintains a dbt project, the useful question is less "is it faster?" and more "will my project still build, and what will break first?". The good news is that you can answer that before switching anything in production. Here is what changed, how the naming now works, and a step-by-step way to test a project safely.

First, untangle the names

The naming changed at the same time as the engine, which is half the confusion. As of November 2026:

  • dbt v2 (package dbt) is the new Rust-based engine that used to be called Fusion. It is free to install and is the recommended distribution, but it is not entirely Apache 2.0 licensed.

  • dbt OSS (package dbt-oss) is the subset of v2 built only from Apache 2.0 components, for organisations that require an open-source runtime.

  • dbt v1 is the dbt Core you know, still Apache 2.0.

The DuckDB team's write-up of the release dates dbt 2.0.0 to 14 September 2026, and notes the CLI now brands itself as "dbt (proprietary)" or "dbt-oss (open source)". A recap of the dbt Summit in September adds a trap worth knowing: installing dbt-core now pulls in dbt OSS, so if you intend to stay on v1 for a while, pin your version in requirements.txt today. The same recap says 1.13 will be the final 1.x minor release.

What actually changes for your project

The official upgrade guide says project language and DAG semantics carry over, so a project that is clean on v1 should "work as before, just faster". The catch is the word "clean". v2 is much stricter about validation. A useful way to think about it: v1 was a teacher who marked your homework and let small spelling mistakes slide; v2 hands it back unmarked until you fix them.

The changes most likely to bite an analytics project:

  • Unknown or misspelled config keys now error at parse time. A stray materialised: (British spelling) that v1 silently ignored will stop the build.

  • Missing macros, variables and generic tests fail during dbt parse, not later at compile time.

  • --models and -m raise an error. Use --select or -s. Check your scheduler, Makefile and CI scripts, not only your memory.

  • config.get() no longer reads from meta. If your macros pull custom metadata that way, switch to config.meta_get().

  • Standalone YAML anchors must sit under a top-level anchors: key, and recursive anchors are not supported.

  • dbt build now runs all unit tests first, then the rest of the DAG. Expect a different order in your logs.

  • Seeds: a trailing comma in a CSV no longer creates an empty extra column. If a downstream model selected that phantom column, it will break.

One reassuring detail: v2 writes a manifest compatible with v1, so the guide says the two can run side by side with state:modified and --defer. You don't have to switch the whole team on one day.

A five-step way to test before you switch

1. Clear every deprecation warning on v1

The upgrade guide is blunt: resolve all deprecation warnings first, including old ones and those introduced in v1.10. Run a parse on your current version and read the warnings rather than scrolling past them.

2. Let dbt-autofix do the boring part

dbt Labs maintains dbt-autofix, which rewrites YAML and SQL for many known deprecations. Its README recommends running it through uv. Preview the changes first without touching any files:

uvx dbt-autofix deprecations --dry-run

Then apply them (the README says this is safe if your project is in git), and check your packages for v2 compatibility:

uvx dbt-autofix deprecations
uvx dbt-autofix packages --dry-run

Commit before you run it, then review the diff like any other pull request. Automated fixes are only as good as your review.

3. Try the v2 parser from inside v1.12

If you are on dbt 1.12, the guide describes an opt-in --use-v2-parser flag that hands parsing to the new engine without changing anything else. It is the lowest-risk way to see which files v2 rejects.

dbt parse --use-v2-parser

4. Check your adapter and packages

As of early November 2026 the upgrade guide lists BigQuery, Databricks, Redshift and Snowflake, plus DuckDB (CLI only), Spark (CLI only, beta) and ClickHouse (private beta). If you are on Postgres, it is not on that list yet, so stay on v1 for now. For packages, look for 2.0.0 inside each package's require-dbt-version range, for example ">=1.10.0,<3.0.0".

5. Run v2 in a separate environment and compare

Install v2 in a fresh virtual environment, point it at a development target, and run your usual build. Compare row counts on your five most important models against the v1 output. If the numbers match and the run completes, you have real evidence, not a hunch, that the upgrade is safe.

The DuckDB shortcut for local testing

Here is a nice side effect for anyone who prototypes locally. According to the DuckDB post, v2 ships with a built-in DuckDB adapter: it downloads the driver on first run, so there is no separate dbt-duckdb package to install. A profile can be as small as this:

my_project:
  target: dev
  outputs:
    dev:
      type: duckdb
      path: ./warehouse.duckdb

If you already use DuckDB for analysis, our DuckDB 2.0 upgrade checklist covers the engine side. The same post shows dbt parse --generate-info-schema writing project metadata as Parquet files you can query directly, which is handy for auditing a large project without parsing manifest.json.

Common mistakes to avoid

  • Upgrading by accident. An unpinned dbt-core in CI can move you to dbt OSS on the next install. Pin first, upgrade on purpose.

  • Trusting speed claims as your reason to move. dbt Labs says v2 parses a 10,000-model project up to 10 times faster. That is a vendor figure for very large projects; a 150-model project may barely notice. Measure your own parse and run times before and after.

  • Fixing errors by deleting tests. If v2 rejects a generic test because a macro is missing, restore the macro. Deleting the test hides a data quality check you wanted.

  • Switching tools and engines at once. If you are also weighing a move from pandas to Polars, as in our Polars 2.0 guide for pandas users, do one migration at a time so you know which change caused which difference.

Should you upgrade now?

If your adapter is supported and your project parses cleanly with the v2 parser, there is little reason to wait: v1 stays supported, but new features land in v2 only. If you are on an unsupported adapter, or your warning list is long, pin v1, schedule an afternoon for autofix and review, and come back when the parse is clean. Either way, the testing steps above cost a couple of hours and save you from finding out in production.

Divya Nair

Written by

Divya Nair

Keep reading

More from Divya Nair

More from Divya Nair

More in Guides & Tutorials

Have a story of your own?

Publisha is free to start. Write with AI that keeps your voice, and publish in a click.