Skip to main content

dbt v2 package upgrade guide

Learn how to upgrade your packages to be compatible with dbt v2.

Back to guides
dbt v2
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 dbt v2-compatible. A dbt v2-compatible package:

    • Supports dbt v2 version 2.0.0
    • Uses the require-dbt-version config to signal compatibility in the dbt package hub
    • Aligns with the latest JSON schema introduced in dbt v1.10.0

    In this guide, we'll go over:

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

    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 dbt v2. 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, dbt v2 warns today and errors in a future release, matching dbt v1 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 dbt v2-compatible.
    • A dbt v2 installation or test environment — You can use dbt v2 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 dbt v2 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 dbt v2​

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

    Running your integration tests with dbt v2​

    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 dbt v2 by running the following dbtf build command (or whatever dbt v2 executable is available in your environment).
    3. If there are no errors, your package likely supports dbt v2 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, dbt v2-compatible dbt project that installs your package and has a packages.yml or dependencies.yml file.
    2. Run it with dbt v2 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 dbt v2.

    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 v1 and dbt v2. dbt Labs uses this release metadata to mark your package with a dbt v2-compatible badge in the dbt package hub. Packages without this metadata don't display the dbt v2-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 dbt v2-compatible.
    3. (Optional) Announce it in #package-ecosystem on dbt Slack if you’d like.
    CI dbt v2 testing

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

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

    • Created a v2 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)
    • Celebrate your new dbt v2-compatible badge 🎉

    Final thoughts​

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

    By upgrading now, you’re ensuring a smoother experience for users, paving the way for the next generation of dbt projects, and helping dbt v2 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 dbt v2-compatible.

     Why do we need to update our package?

    dbt v2 and dbt 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. dbt v2-compatible packages display a badge in the dbt package hub.

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

     How do I test v2 in CI?

    Add a separate job that installs dbt v2 (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 dbt v2.

     How will users know my package is v2-compatible?

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

    dbt v2-compatible packages also display a badge in the dbt package 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