Upgrade to Fusion part 1: Preparing to upgrade

This guide helps you prepare for an in-place upgrade from dbt Core to the dbt Fusion engine in the dbt platform.

Back to guides

dbt Fusion engine

dbt platform

Upgrade

Intermediate

Menu

Introduction

private preview

The dbt Fusion engine is available as a private preview for all tiers of dbt platform accounts. dbt Labs is enabling Fusion only on accounts that have eligible projects. Following the steps outlined in this guide doesn't guarantee Fusion eligibility.

The dbt Fusion engine represents the next evolution of data transformation. dbt has been rebuilt from the ground up but at its most basic, Fusion is a new version, and like any new version you should take steps to prepare to upgrade. This guide will take you through those preparations.

If Fusion is brand new to you, take a look at our comprehensive documentation on what it is, how it behaves, and what's different from dbt Core before getting started with this guide. Once you're caught up, it's time to begin preparing your projects for the speed and power that Fusion has to offer.

Prerequisites

This guide will cover the preparations for upgrading to the dbt Fusion engine and is intended for customers already using the dbt platform with a version of dbt Core. If you're brand new to dbt, check out our quickstart guides.

To follow the steps in this guide, you must meet the following prerequisites:

• You're using a dbt platform account on any tier.
• You have a developer license.
• You have proper permissions to edit projects.
• Your project is using a Fusion supported adapter:
   BigQuery

  • Service Account / User Token
  • Native OAuth
  • External OAuth
    • Workload Identity Federation isn't currently supported in Fusion. Use a Native OAuth connection or service account instead. Support coming soon.
  • Required permissions
   Databricks

  • Service Account / User Token
  • Native OAuth
   Redshift

  • Username / Password
  • IAM profile
   Snowflake

  • Username / Password
  • Native OAuth
  • External OAuth
  • Key pair using a modern PKCS#8 method
  • MFA
   Apache Spark (Fusion CLI only)

  • Thrift
    • Simple Authentication and Security Layer (SASL) PLAIN
    • No SASL (NOSASL)
  • Livy
    • Basic authentication (username and password)
    • When deployed on Amazon Web Services (AWS): AWS Signature Version 4
      • Supports authentication using single sign-on, service accounts, or user tokens
   DuckDB (Fusion CLI only)

  DuckDB does not require authentication — it runs locally on your machine.

Upgrading your first project

Start with smaller, newer, or more familiar projects first. This makes it easier to identify and troubleshoot any issues before upgrading larger, more complex projects.

Enable Fusion readiness features

The Fusion readiness panel in the dbt platform and shows each project's eligibility status and blockers, is being rolled out in phases. If it hasn't been automatically enabled for your account yet, an account admin can manually enable it. This lets admins and developers see which projects and jobs are eligible for Fusion, identify blockers, and initiate the upgrade once preparation is complete.

Step 1: Enable the readiness toggle

This step requires account admin access in dbt platform:

1. Click your account name in the left sidebar and select Account settings.
2. Navigate to the Account screen and click Edit.
3. Scroll to the Settings section and select the checkbox next to Enable Fusion readiness & upgrade features.
4. Click Save.

Once enabled:

• All admins and developers can see each project's Fusion readiness status, including which jobs are eligible or ineligible for Fusion and why.
• Admins can initiate the Fusion upgrade from development environments, environment settings, and job settings (subject to existing permissions).

Step 2: Restrict upgrade access (optional)

By default, any user who can see the upgrade assistant can use it to initiate an upgrade. To limit upgrade execution to designated users, you can enable an additional access control toggle.

Enterprise tier accounts only

The Enable restricted Fusion upgrade permissions toggle is only available to Enterprise/Enterprise+ accounts that have been granted this entitlement. Contact your account manager if you need this capability.

1. In the same Account settings screen, select the checkbox next to Enable restricted Fusion upgrade permissions.
2. Click Save.

When enabled, only users assigned the Fusion admin permission set (scoped to specific projects) can execute the upgrade. For instructions on assigning this permission, refer to Assign upgrade access in Part 2 of this guide.

The Fusion readiness panel

With the readiness experience enabled, you can monitor your project's eligibility as you work through the preparation steps below. The panel shows which jobs are eligible or ineligible for Fusion and why.

The Fusion readiness checklist

Common ineligibility reasons include:

• Environment(s) not on the Latest [release track](/docs/dbt-versions/cloud-release-tracks#which-release-tracks-are-available]
• Not using a supported data platform
• Project doesn't have at least one successful job run
• Jobs that haven't run in the last 7 days or have recent failures

As you complete the steps in this guide, check the readiness panel to see your eligibility improve.

Upgrade to the latest dbt Core version

Before upgrading to Fusion, you need to move your environments to the Latest dbt Core release track. The Latest track includes all the features and tooling to help you prepare for Fusion. It ensures the smoothest upgrade experience by validating that your project doesn't rely on deprecated behaviors.

Test before you deploy

Always test version upgrades in development first. Use the Override dbt version feature to safely try the Latest release track without affecting your team or production runs.

Step 1: Test in development (using override)

Test the Latest release track for your individual account without changing the environment for your entire team:

1. Click your account name in the left sidebar and select Account settings.
2. Select Credentials from the sidebar and choose your project.
3. In the side panel, click Edit and scroll to User development settings.
4. Select Latest from the dbt version dropdown and click Save.

Override dbt version in your account settings

5. Launch the Studio IDE or dbt CLI and test your normal development workflows.
6. Verify the override is active by running any dbt command and checking the System Logs. The first line should show Running with dbt= and your selected version. If the version number is v1.11 or higher, you're on the right path to Fusion readiness.

If everything works as expected, proceed to the next step to start upgrading your environments. If you encounter deprecation warnings, don't fear! We'll address those later in this guide. If you encounter errors, revert to your previous version and refer to the version upgrade guides to resolve any differences between your current version and the latest available dbt Core version.

Step 2: Upgrade your development environment

After successfully testing your individual development environment with the override, upgrade the development environment for the entire project (be sure to give your team notice!):

1. Navigate to Environments in your project settings.
2. Select your Development environment and click Edit.
3. Click the dbt version dropdown and select Latest.
4. Click Save to apply the changes.

Upgrade development environment to Latest dbt Core release track

Remove your override

Once your development environment is upgraded, you can remove your personal override by returning to your account credentials and selecting the same version as your environment.

Step 3: Upgrade staging and pre-production

If your organization has staging or pre-production environments, upgrade these before production:

1. Navigate to Environments and select your staging/pre-production environment.
2. Click Edit and select Latest from the dbt version dropdown.
3. Click Save.
4. Run your jobs in this environment for a few days to validate everything works correctly.

This provides a final validation layer before upgrading production environments.

Step 4: Upgrade your production environment

After validating in staging (or development if you don't have staging), upgrade your production environment:

1. Navigate to Environments and select your Production environment.
2. Click Edit and select Latest from the dbt version dropdown.
3. Click Save to apply the changes.
4. Monitor your first few production runs to ensure everything executes successfully.

Step 5: Update jobs

While environments control the dbt version for most scenarios, some older job configurations may have version overrides. Review your jobs and update any that specify a dbt version to ensure they use the environment's Latest release track.

Resolve all deprecation warnings

Fusion enforces strict validation and won't accept deprecated code that currently generates warnings in dbt Core. You must resolve all deprecation warnings before upgrading to Fusion. Fortunately, the autofix tool in the Studio IDE can automatically resolve most common deprecations for you.

VS Code extension

This guide provides steps to resolve deprecation warnings without leaving dbt platform. If you prefer to work in the VS Code or Cursor editors locally, you can run the autofix in our dbt VS Code extension. Check out the installation guide for more information about those workflows.

What the autofix tool handles

The autofix tool can resolve many deprecations automatically, including:

• Moving custom configurations into the meta dictionary
• Fixing duplicate YAML keys
• Correcting unrecognized resource properties
• Updating deprecated configuration patterns

Check out the autofix readme for a complete list of the deprecations it addresses.

Fusion package compatibility

In addition to deprecations, the autofix tool attempts to upgrade packages to the lowest supported Fusion-compatible version. Check out package support for more information about Fusion compatibility.

Step 1: Create a new branch

Before running the autofix tool, create a new branch to isolate your changes:

1. Navigate to the Studio IDE by clicking Studio in the left-side menu.
2. Click the Version control panel (git branch icon) on the left sidebar.
3. Click Create branch and name it something descriptive like fusion-deprecation-fixes.
4. Click Create to switch to your new branch.

Save before autofixing

The autofix tool will modify files in your project. Make sure to commit or stash any unsaved work to avoid losing changes.

Step 2: Run the autofix tool

Now you're ready to scan for and automatically fix deprecation warnings:

1. Click the three-dot menu in the bottom right corner of the Studio IDE.
2. Select Check & fix deprecations.

Access the Studio IDE options menu

The tool runs dbt parse --show-all-deprecations --no-partial-parse to identify all deprecations in your project. This may take a few moments depending on your project size.

3. When parsing completes, view the results in the Command history panel in the bottom left.

View command history and deprecation results

Step 3: Review and apply autofixes

After the deprecation scan completes, review the findings and apply automatic fixes:

1. In the Command history panel, review the list of deprecation warnings.
2. Click the Autofix warnings button to proceed.

Click Autofix warnings to resolve deprecations automatically

3. In the Proceed with autofix dialog, review the warning and click Continue.

Confirm autofix operation

The tool automatically modifies your project files to resolve fixable deprecations, then runs another parse to identify any remaining warnings.

4. When complete, a success message appears. Click Review changes.

Autofix complete

Step 4: Verify the changes

Review the changes made by the autofix tool to ensure they're correct:

1. Open the Version control panel to view all modified files.
2. Click on individual files to review the specific changes.
3. Look for files with moved configurations, corrected properties, or updated syntax.
4. If needed, make any additional manual adjustments.

Step 5: Commit your changes

Once you're satisfied with the autofix changes, commit them to your branch:

1. In the Version control panel, add a descriptive commit message like "Fix deprecation warnings for Fusion upgrade".
2. Click Commit and sync to save your changes.

Step 6: Address remaining deprecations

If the autofix tool reports remaining deprecation warnings that couldn't be automatically fixed:

1. Review the warning messages in the Command history panel. Each warning includes the file path and line number.
2. Manually update the code based on the deprecation guidance:
   • Custom inputs should be moved to the meta config.
   • Deprecated properties should be updated to their new equivalents.
   • Refer to specific version upgrade guides for detailed migration instructions.
3. After making manual fixes, run Check & fix deprecations again to verify all warnings are resolved.
4. Commit your changes.

Step 7: Merge to your main branch

Once all deprecations are resolved:

1. Create a pull request in your git provider to merge your deprecation fixes.
2. Have your team review the changes.
3. Merge the PR to your main development branch.
4. Ensure these changes are deployed to your environments before proceeding with the Fusion upgrade.

Validate and upgrade your dbt packages

Run autofix first

This section contains instructions for manual package upgrades. We recommend running the autofix tool before taking these steps.

The autofix tool finds packages incompatible with Fusion and upgrades them to the lowest compatible version. For more information, check out package support.

dbt packages extend your project's functionality, but they must be compatible with Fusion. Most commonly used packages from dbt Labs (like dbt_utils and dbt_project_evaluator) and many community packages already support Fusion. Before upgrading, verify your packages are compatible and upgrade them to the latest versions. Check for packages that support version 2.0.0, or ask the maintainer if you're unsure.

What if a package isn't compatible?

If a critical package isn't yet compatible with Fusion:

• Check with the package maintainer about their roadmap.
• Open an issue requesting Fusion support.
• Consider contributing the compatibility updates yourself.
• Try it out anyway! The incompatible portion of the package might not impact your project.

Package compatibility messages

Inconsistent Fusion warnings and dbt-autofix logs

Fusion 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-version and whether require-dbt-version contains 2.0.0.
• Some packages are already Fusion-compatible even though package maintainers haven't yet updated require-dbt-version.
• dbt-autofix knows 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]

Step 1: Review your current packages

Identify which packages your project uses:

1. In the Studio IDE, open your project's root directory.
2. Look for either packages.yml or dependencies.yml file.
3. Review the list of packages and their current versions.

Your file will look something like this:

packages:
  - package: dbt-labs/dbt_utils
    version: 1.0.0
  - package: dbt-labs/codegen
    version: 0.9.0

Step 2: Check compatibility and find the latest package versions

Review the dbt package hub to see verified Fusion-compatible packages by checking that the require-dbt-version configuration includes 2.0.0 or higher. Refer to package support for more information.

For packages that aren't Fusion-compatible:

• Visit the package's GitHub repository.
• Check the README or recent releases for Fusion compatibility information.
• Look for issues or discussions about Fusion support.

For each package, find the most recent version:

• Visit dbt Hub for packages hosted there.
• For packages from GitHub, check the repository's releases page.
• Note the latest version number for each package you use.

For Hub packages, you can use version ranges to stay up-to-date:

packages:
  - package: dbt-labs/dbt_utils
    version: [">=1.0.0", "<3.0.0"]  # Gets latest 1.x or 2.x version

Step 3: Update your package versions

Update your packages.yml or dependencies.yml file with the latest compatible versions:

1. In the Studio IDE, open your packages.yml or dependencies.yml file.

2. Update each package version to the latest compatible version.

3. Save the file.

   Before update:

   packages:
   - package: dbt-labs/dbt_utils
      version: 0.9.6
   - package: dbt-labs/codegen
      version: 0.9.0

   After update:

   packages:
   - package: dbt-labs/dbt_utils
      version: [">=1.0.0", "<2.0.0"]
   - package: dbt-labs/codegen
      version: [">=0.12.0", "<1.0.0"]

Step 4: Install updated packages

After updating your package versions, install them:

1. In the Studio IDE command line, run:

   dbt deps --upgrade

The --upgrade flag ensures dbt installs the latest versions within your specified ranges, updating the package-lock.yml file.

2. Review the output to confirm all packages installed successfully.
3. Check that the package-lock.yml file was updated with the new package versions.

About package-lock.yml

The package-lock.yml file pins your packages to specific versions for reproducible builds. We recommend committing this file to version control so your entire team uses the same package versions.

Step 5: Test your project with updated packages

After upgrading packages, test your project to ensure everything works:

1. Run a subset of your models to verify basic functionality:

   dbt run --select tag:daily

2. Run your tests to catch any breaking changes (exact command may vary):

   dbt test

3. If you encounter issues:

   • Review the package's changelog for breaking changes
   • Adjust your code to match new package behavior
   • If problems persist, temporarily pin to an older compatible version (if possible)

Step 6: Commit package updates

Once you've verified the updated packages work correctly:

1. In the Version control panel, stage your changes:

   • packages.yml or dependencies.yml
   • package-lock.yml

2. Add a commit message like "Upgrade dbt packages for Fusion compatibility".

3. Click Commit and sync.

Update your jobs

Use the Fusion readiness panel to validate your jobs against the dbt Fusion engine and fix any issues you find.

Review your jobs

The readiness panel shows how many jobs are ineligible for Fusion or have an unknown eligibility status:

note

If a job has not run in the last 7 days, you must run it once for the debugging options to be available.

1. Open the jobs list using either path:
   • From the main menu, go to Orchestration → Jobs.
   • From the readiness panel, click Review jobs.
   Shortcut to review your jobs from the readiness panel
2. Find the Fusion eligibility icon to the right of your jobs. Click Review job for any job that is ineligible or has an unknown eligibility status.
   Take action on your jobs to make them Fusion eligible.
3. Click Debug on Fusion and choose one of the following:
   • Debug in Studio
   • Debug in Studio with Copilot
   • Run once on Fusion

Debug in Studio

In the Studio IDE, run Fusion in your development environment to review project warnings and errors:

1. Click Debug in Studio. The Studio IDE opens and selects the Problems tab.

2. dbt sets only your development environment to Fusion.

Running Fusion in development

3. Review the warnings or errors in the Problems tab.
4. Fix the issues directly or run the autofix tool.
5. When the project runs with no warnings or errors, commit and publish your changes.
6. After you merge the changes, wait for the job to run again or run it manually.

Debug in Studio with Copilot Beta

If you have access to Developer agent and Copilot with AI features enabled, you can use the Fusion migration workflow skill. This skill can help you fix compatibility errors directly from the Studio IDE using Copilot — no manual log investigation needed. It classifies every error, applies validated fixes automatically, and surfaces what's blocked.

info

The Fusion migration workflow is accessible through the Developer agent in the Studio IDE. If you're using VS Code or the dbt CLI, use the autofix tool instead.

1. From the job list, click the Review job button for a job with a successful run.
   • If you don't see the Review job button, enable the Show Fusion eligibility toggle in the job list.
2. In the Fusion eligibility unknown for this job pop-up, click Debug in Studio with Copilot.
3. dbt redirects you to the Studio IDE and sets your personal development environment to Fusion.
4. Copilot opens and automatically triggers the Fusion migration skill with this prompt:

   I need help fixing Fusion compatibility issues in this project. Please investigate and resolve any deprecation warnings or incompatibilities. Please use the migrating-dbt-core-to-fusion skill to guide this.
5. Review and approve Copilot's permission requests so it can run the commands it needs.
6. The Developer agent iteratively runs dbt compile, reads the results, and applies fixes until it reaches a successful compile or encounters an error it can't resolve. If it gets blocked, it exits cleanly, explains what it could not fix, and creates and links to a markdown file summarizing all changes made.
7. When the project compiles with no warnings or errors, commit and publish your changes.
8. After you merge the changes, wait for the job to run again or run it manually on Fusion.

The Developer Agent's fusion migration workflow triaging and fixing Fusion compatibility errors in the Studio IDE.

Run once on Fusion

When you are confident a job is ready for Fusion, you can run it once on the engine without changing environment-wide settings:

1. Click Run once on Fusion.
2. The job window opens and dbt runs the job on Fusion without changing other jobs or environment settings.
3. When the job succeeds, click Override eligibility status to update the eligibility status.
   Override the eligibility status of a successful job.

Congratulations! You have validated Fusion eligibility for your jobs.

Your job is now ready for Fusion!

What's next?

With limitations identified and addressed, you've completed all the preparation steps. Your project is now ready to upgrade to Fusion!

Check out Part 2: Making the move

Was this page helpful?

Privacy policyCreate a GitHub issue

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.