By dbt Core v2.0 hit alpha on June 1 and the data engineering community is mostly focused on the wrong thing. Yes, the Rust-based parser is 30 times faster than the Python one it replaces. Yes, the full project compilation is twice as quick. None of that matters if you upgrade on GA day and discover your CI pipeline — the one built in 2021 — has been using --models for five years and v2 doesn’t recognize the flag anymore. The speed wins are real, but they’re a reward for teams that migrate cleanly. This is the migration guide.
What Changed Under the Hood
dbt Core v2.0 moves from a Python parser to a Rust-based engine derived from the dbt Fusion project. This isn’t an incremental improvement — it’s a rewrite of the core parsing and compilation layer. The practical consequence is that v2 enforces a stricter project language spec and has a native understanding of SQL across major warehouse dialects: BigQuery, Snowflake, Databricks, and Redshift.
The new version ships in two free distributions:
- dbt Fusion — The recommended path for most teams. Built on the same Apache 2.0 core, extended with SQL comprehension, column-level lineage, and the new
dbt lintcommand. Some premium features require a license key, but the base product is free. - dbt Core v2.0 — Pure Apache 2.0, no proprietary components. Identical engine underneath. For teams with strict license requirements or those building tooling on top of the OSS codebase.
Both distributions share the same project language, the same DAG semantics, and the same manifest format. If you’re not sure which to pick, install Fusion.
What Breaks on Upgrade
This is where most teams will lose time. v2 drops all functionality that was deprecated in v1.x — no grace period, no soft warnings. Deprecation warnings from v1.10 onward are now hard errors.
The most common breakage is the --models flag. It was deprecated in v0.21 — that’s 2021 — in favor of --select. dbt Core continued to accept it with a warning for years. v2 does not. If your Makefile, your CI script, your Airflow task, or your shell alias uses --models or -m, it will fail on v2. Same story for --resource-type, which should be --resource-types.
Beyond flags, v2 applies strict validation to project configurations. Loose or malformed description: fields that the Python parser quietly accepted now surface as errors. The strictness is intentional — it makes the dbt project language a well-defined spec rather than a lenient suggestion — but it does mean projects with accumulated technical debt will surface issues on upgrade.
Fix It Before You Upgrade: dbt-autofix
dbt Labs ships a CLI tool specifically for this. Install it, run it against your project, and let it handle the mechanical fixes before you touch the v2 binary:
pip install dbt-autofix
dbt-autofix check # Shows what would be changed
dbt-autofix fix # Applies the changesAs of version 0.17.0, dbt-autofix also checks package dependencies for Fusion compatibility and can upgrade them automatically. Run it before you do anything else.
The Migration Path
The recommended sequence has four steps, and the order matters:
Step 1 — Upgrade to v1.12. This is the bridge release. It enforces many of the same behavior changes as v2 and ships the Rust-based parser as an opt-in flag. Get here before you think about v2.
Step 2 — Run the v2 parser test. From v1.12, you can test v2 compatibility without migrating:
dbt parse --use-v2-parserIf this command succeeds, your project is ready. If it surfaces errors, you now know what to fix while still on a stable v1.12 base. This is the cheapest way to find out.
Step 3 — Resolve all deprecation warnings. Run dbt parse --show-all-deprecations and address everything it flags. Use dbt-autofix for the mechanical changes. For anything it can’t auto-fix, check the official v2 upgrade guide.
Step 4 — Migrate dev, then staging, then prod. Install v2 in your development environment first. Validate your full pipeline end-to-end. Promote to staging. Only touch production after two clean runs at lower environments.
Package Compatibility
The official dbt Labs packages are already compatible with v2: dbt_utils, audit_helper, dbt_external_tables, and dbt_project_evaluator are safe to use as-is. For external packages, check whether their require-dbt-version bounds include 2.0.0 — a package pinned to <2.0.0 will reject the install. The dbt-autofix tool checks this automatically from v0.17.0 onward.
What You Get After
Once you’re through the migration, the performance difference is not subtle. Parse times drop by a factor of 30 on large projects. Full compilation is twice as fast. The new dbt lint command (Fusion only) is SQLFluff-compatible — same rule codes, same .sqlfluff config, same noqa comments — but runs 40 to 1,500 times faster than SQLFluff depending on project size. Artifacts move from JSON to Parquet, which is smaller and faster to process downstream.
The strictness that causes migration friction is also a feature once you’re on the other side. A project that parses cleanly in v2 is a project with a well-defined schema that third-party tooling can build against reliably.
The Bottom Line
v2.0 is in alpha and not production-ready for most teams. But the right time to run dbt parse --use-v2-parser is now, while you have time to fix what it finds at your own pace. The teams that will spend three days on upgrade day are the ones that waited for GA to discover five years of deprecated flag debt. Don’t be those teams.
Track the official v2 announcement for GA timing, use dbt-autofix to get ahead of the deprecations now, and read the dbt lint documentation to understand what Fusion adds on top of the core.
