Skip to content
16 changes: 13 additions & 3 deletions dbt-guides/dbt-fusion-migration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,29 @@ Unlike dbt 1.10 which is an incremental update, Fusion represents a fundamental
Important: dbt Fusion is still in beta, which means some dbt functionality is not supported at present. Please review the [dbt Fusion supported features and current limitations documentation](https://docs.getdbt.com/docs/fusion/supported-features) before proceeding with this migration.
</Warning>

### Using dbt Fusion with Lightdash

dbt Fusion projects are compatible with Lightdash, but the Lightdash CLI currently requires **dbt Core 1.10+** to be installed locally.

While dbt Fusion produces a dbt Core–compatible manifest, the Lightdash CLI still executes `dbt` commands (such as `dbt --version`) and cannot run in a Fusion-only environment. You may use dbt Fusion for local development, but dbt Core must be installed alongside it for the Lightdash CLI to work.

This does not affect Lightdash Cloud compilation, which always uses dbt Core 1.10+ on Lightdash servers regardless of whether you use dbt Fusion locally.

## Recommended Migration Process
### Step 1: Upgrade to dbt 1.10 and Fix Warnings

1. Upgrade your dbt environment to version 1.10 or later (see dbt instructions [here](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10)).
2. Use Lightdash's [MetaMove CLI](https://docs.lightdash.com/dbt-guides/dbt-1.10-migration#automated-migration-with-metamove) to automatically migrate `meta` and `tags` from top-level properties to `config` blocks.
3. Run your dbt project and address any other deprecation warnings before proceeding. Note you can also use [dbt-autofix](https://github.com/dbt-labs/dbt-autofix) to automatically resolve many deprecation warnings.

<Note>
We'll be updating all documentation code snippets to include dbt v1.10+ YAML structure (`config.meta`) soon.
</Note>

### Step 2: Migrate to Fusion (only required for dbt Core users)
Once all deprecation warnings are resolved, dbt Core users will need to follow the steps below to migrate to the dbt Fusion engine. dbt Cloud users, however, can wait for automatic rollout - dbt Labs will handle the dbt Fusion migration automatically.

#### For dbt Core Users:
1. Check that you meet the [dbt Fusion migration prerequisites](https://docs.getdbt.com/docs/fusion/install-fusion#prerequisites)
2. Install the dbt Fusion engine following the [installation guide](https://docs.getdbt.com/docs/fusion/install-fusion#install-fusion)
3. Run your project with dbt Fusion to identify any compatibility issues.


3. Run your project with dbt Fusion to identify any compatibility issues.