Skip to main content

Fusion package upgrade guide

Learn how to upgrade your packages to be compatible with the dbt Fusion engine.

Back to guides
dbt Fusion engine
Advanced
Menu

    Introduction​

    Thank you for being part of the dbt's package hub community and maintaining packages! Your work makes dbt’s ecosystem possible and helps thousands of teams reuse trusted models and macros to build faster, more reliable analytics.

    This guide helps you upgrade your dbt packages to be Fusion-compatible. A Fusion-compatible package:

    In this guide, we'll go over:

    • Updating your package to be compatible with Fusion
    • Testing your package with Fusion
    • Updating the require-dbt-version config to include 2.0.0
    • Updating your README to note that the package is compatible with Fusion

    Who is this for?​

    This guide is for any dbt package maintainer, like dbt-utils, that's looking to upgrade their package to be compatible with Fusion. Updating your package ensures users have the latest version of your package, your package stays trusted on dbt package hub, and users benefit from the latest features and bug fixes.

    A user stores their package in a packages.yml or dependencies.yml file. If a package excludes 2.0.0, Fusion warns today and errors in a future release, matching dbt Core behavior.

    This guide assumes you're using the command line and Git to make changes in your package repository. If you're interested in creating a new package from scratch, we recommend using the dbt package guide to get started.

    Prerequisites​

    Before you begin, make sure you meet the following:

    • dbt package maintainer — You maintain a package on dbt's package hub or are interested in creating one.
    • dbt-autofix installed — Install dbt-autofix to automatically update the package's YAML files to align with the latest dbt updates and best practices. We recommend using/installing uv/uvx to run the tool.
      • Run the command uvx dbt-autofix for the latest version of the tool. For more installation options, see the official dbt-autofix doc.
    • Repository access — You’ll need permission to create a branch and release updates/a new version of your package. You’ll need to tag a new version of your package once it’s Fusion-compatible.
    • A Fusion installation or test environment — You can use Fusion locally (using the dbtf binary) or in your CI pipeline to validate compatibility.
    • CLI and Git usage — You’re comfortable using the command line and Git to update the repository.

    Upgrade the package​

    This section covers how to upgrade your package to be compatible with Fusion by:

    If you're ready to get started, let's begin!

    Run dbt-autofix​

    1. Before you begin, make sure you have dbt-autofix installed. If you don't have it installed, run the command uvx dbt-autofix. For more installation options, see the official dbt-autofix doc.

    2. In your dbt package repository, create a branch to work in. For example:

      git checkout -b fusion-compat

    3. Run dbt-autofix deprecations in your package directory so it automatically updates your package code and rewrites YAML to conform to the latest JSON schema:

      dbt-autofix deprecations

    Test package with Fusion​

    Now that you've run dbt-autofix, let's test your package with Fusion to ensure it's compatible before updating your require-dbt-version config. Refer to the Fusion limitations documentation for more information on what to look out for. You can test your package two ways:

    Running your integration tests with Fusion​

    If your package includes an integration_tests/ folder (like dbt-utils), follow these steps:

    1. Navigate to the folder (cd integration_tests) to run your tests. If you don't have an integration_tests/ folder, you can either create one or navigate to the folder that contains your tests.
    2. Then, run your tests with Fusion by running the following dbtf build command (or whatever Fusion executable is available in your environment).
    3. If there are no errors, your package likely supports Fusion and you're ready to update your require-dbt-version. If there are errors, you'll need to fix them first before updating your require-dbt-version.

    Manually validating your package​

    If your package doesn't have integration tests, follow these steps:

    1. Create a small, Fusion-compatible dbt project that installs your package and has a packages.yml or dependencies.yml file.
    2. Run it with Fusion using the dbtf run command.
    3. Confirm that models build successfully and that there are no warnings. If there are errors/warnings, you'll need to fix them first. If you still have issues, reach out to the #package-ecosystem channel on Slack for help.

    Update require-dbt-version​

    Only update the require-dbt-version config after testing and confirming that your package works with Fusion.

    1. Update the require-dbt-version in your dbt_project.yml to include 2.0.0. We recommend using a range to ensure stability across releases:

      require-dbt-version: [">=1.10.0,<3.0.0"]

      This signals that your package supports both dbt Core and Fusion. dbt Labs uses this release metadata to mark your package with a Fusion-compatible badge (to be introduced shortly) in the dbt package hub. Packages without this metadata don't display the Fusion-compatible badge.

    2. Commit and push your changes to your repository.

    Publish a new release​

    1. After committing and pushing your changes, publish a new release of your package by merging your branch into main (or whatever branch you're using for your package).
    2. Update your README to note that the package is Fusion-compatible.
    3. (Optional) Announce it in #package-ecosystem on dbt Slack if you’d like.
    CI Fusion testing

    When possible, add a step to your CI pipeline that runs dbtf build or equivalent to ensure ongoing Fusion compatibility.

    Your package is now Fusion-compatible and the dbt package hub reflects these changes. To summarize, you've now:

    • Created a fusion compatible branch
    • Run dbt-autofix deprecations
    • Reviewed, committed, and tested changes
    • Updated require-dbt-version: [">=1.10.0,<3.0.0"] to include 2.0.0
    • Published a new release
    • Announced the update (optional)

    Final thoughts​

    Now that you've upgraded your package to be Fusion-compatible, users can use your package with Fusion! 🎉

    By upgrading now, you’re ensuring a smoother experience for users, paving the way for the next generation of dbt projects, and helping dbt Fusion reach full stability.

    If you have questions or run into issues:

    Lastly, thank you for your help in making the dbt ecosystem stronger — one package at a time 💜.

    Frequently asked questions​

    The following are some frequently asked questions about upgrading your package to be Fusion-compatible.

     Why do we need to update our package?

    Fusion and dbt Core v1.10+ use the same new authoring layer. Ensuring your package supports 2.0.0 in your require-dbt-version config ensures your package is compatible with both.

    Updating your package ensures users have the latest version of your package, your package stays trusted on dbt package hub, and users benefit from the latest features and bug fixes. Soon, you'll be able to display a Fusion-compatible badge in dbt package hub.

    If a package excludes 2.0.0, Fusion will warn today and error in a future release, matching dbt dbt Core behavior.

     How do I test Fusion in CI?

    Add a separate job that installs Fusion (dbtf) and runs dbtf build. See this PR for a working example.

    You want to do this to ensure any changes to your package remain compatible with Fusion.

     How will users know my package is Fusion-compatible?

    Users can identify your package as Fusion-compatible by checking for 2.0.0 or higher in the require-dbt-version range config.

    Fusion-compatible packages will soon display a badge on dbt packages hub. This is automatically determined based on your package’s metadata and version requirements.

    Was this page helpful?

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

    0