# Upgrade to dbt v2 part 1: Preparing to upgrade This guide helps you prepare for an in-place upgrade from v1 to v2 in the dbt platform. [Back to guides](../guides.md) [Menu ]() ## Introduction dbt v2 represents the next evolution of data transformation. dbt has been rebuilt from the ground up but at its most basic, dbt v2 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 dbt v2 is brand new to you, take a look at our [comprehensive documentation](../docs/introduction.md) on what it is, how it behaves, and what's different from dbt v1 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 dbt v2 has to offer. ## Prerequisites This guide will cover the preparations for upgrading to dbt v2 and is intended for customers already using the dbt platform with a version of dbt v1. If you're brand new to dbt, check out our [quickstart guides](../guides.md). 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](../docs/platform/manage-access/enterprise-permissions.md) to edit projects. * Your project is using a [supported adapter](../docs/platform/connect-data-platform/about-connections.md?version=2.0)  BigQuery * Service Account / User Token * Native OAuth * External OAuth * [Workload Identity Federation](../docs/platform/manage-access/set-up-bigquery-oauth.md#set-up-bigquery-workload-identity-federation) (Microsoft Entra) * [Required permissions](../docs/local/connect-data-platform/bigquery-setup.md#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  ClickHouse[Private beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * Username / Password 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 dbt v2 readiness features The dbt v2 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](../docs/platform/manage-access/enterprise-permissions.md#account-admin) can manually enable it. This lets admins and developers see which projects and jobs are eligible for dbt v2, 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 dbt v2 readiness & upgrade features**. 4. Click **Save**. Once enabled: * All admins and developers can see each project's dbt v2 readiness status, including which jobs are eligible or ineligible for dbt v2 and why. * Admins can initiate the dbt v2 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 dbt v2 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 dbt v2 upgrade permissions**. 2. Click **Save**. When enabled, only users assigned the [`v2 Migration Admin`](../docs/platform/manage-access/enterprise-permissions.md#v2-migration-admin) permission set (scoped to specific projects) can execute the upgrade. For instructions on assigning this permission, refer to [Assign upgrade access](./upgrade-to-v2.md?step=3#assign-upgrade-access-optional) in Part 2 of this guide. ### The dbt v2 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 dbt v2 and why. [![The dbt v2 readiness checklist](/img/v2/v2-readiness.png?v=2 "The dbt v2 readiness checklist")](#)The dbt v2 readiness checklist Common ineligibility reasons include: * Environment(s) not on the **v1 Latest** [release track](../docs/dbt-versions/dbt-release-tracks.md#which-release-tracks-are-available) * Not using a [supported data platform](../docs/dbt/supported-features.md?version=2.0#requirements) * 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 v1 version Before upgrading to dbt v2, you need to move your environments to the **v1 Latest** [dbt v1 release track](../docs/dbt-versions/dbt-release-tracks.md). The **v1 Latest** track includes all the features and tooling to help you prepare for dbt v2. 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](#step-1-test-in-development-using-override) feature to safely try the **v1 Latest** release track without affecting your team or production runs. ### Step 1: Test in development (using override) Test the **v1 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 **v1 Latest** from the **dbt version** dropdown and click **Save**. [![Override dbt version in your account settings](/img/docs/dbt-platform/platform-configuring-dbt-platform/choosing-dbt-version/example-override-version.png?v=2 "Override dbt version in your account settings")](#)Override dbt version in your account settings 5. Launch the Studio IDE or dbt platform 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 dbt v2 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](./prepare-v2-upgrade.md?step=4). If you encounter errors, revert to your previous version and refer to the [version upgrade guides](../docs/dbt-versions/dbt-upgrade.md) to resolve any differences between your current version and the latest available dbt v1 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 **v1 Latest**. 4. Click **Save** to apply the changes. [![Upgrade development environment to \*\*v1 Latest\*\* release track](/img/docs/dbt-platform/platform-configuring-dbt-platform/choosing-dbt-version/select-development.png?v=2 "Upgrade development environment to **v1 Latest** release track")](#)Upgrade development environment to \*\*v1 Latest\*\* 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 **v1 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 **v1 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](../docs/dbt-versions/upgrade-dbt-platform-version.md#jobs) to ensure they use the environment's v1 Latest release track. ## Resolve all deprecation warnings dbt v2 enforces strict validation and won't accept deprecated code that currently generates warnings in dbt v1. You must resolve all deprecation warnings before upgrading to dbt v2. 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](../docs/install-dbt-extension.md) 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](https://github.com/dbt-labs/dbt-autofix/) for a complete list of the deprecations it addresses. dbt v2 package compatibility In addition to deprecations, the autofix tool attempts to upgrade packages to the lowest supported dbt v2-compatible version. Check out [package support](../docs/dbt/supported-features.md#package-support) for more information about dbt v2 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](/img/docs/dbt-platform/platform-ide/ide-options-menu-with-save.png?v=2 "Access the Studio IDE options menu")](#)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](/img/docs/dbt-platform/platform-ide/command-history.png?v=2 "View command history and deprecation results")](#)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](/img/docs/dbt-platform/platform-ide/autofix-button.png?v=2 "Click Autofix warnings to resolve deprecations automatically")](#)Click Autofix warnings to resolve deprecations automatically 3. In the **Proceed with autofix** dialog, review the warning and click **Continue**. [![Confirm autofix operation](/img/docs/dbt-platform/platform-ide/proceed-with-autofix.png?v=2 "Confirm autofix operation")](#)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](/img/docs/dbt-platform/platform-ide/autofix-success.png?v=2 "Autofix complete")](#)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 dbt v2 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](../docs/dbt-versions/dbt-upgrade.md) 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 dbt v2 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 dbt v2 and upgrades them to the lowest compatible version. For more information, check out [package support](../docs/dbt/supported-features.md#package-support). dbt packages extend your project's functionality, but they must be compatible with dbt v2. Most commonly used packages from dbt Labs (like `dbt_utils` and `dbt_project_evaluator`) and many community packages [already support dbt v2](../docs/dbt/supported-features.md#package-support). 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 dbt v2: * Check with the package maintainer about their roadmap. * Open an issue requesting dbt v2 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 v2 warnings and `dbt-autofix` logs dbt v2 warnings and `dbt-autofix` logs may show different messages about package compatibility. If you use [`dbt-autofix`](https://github.com/dbt-labs/dbt-autofix) while upgrading to v2 in the Studio IDE or dbt VS Code extension, you may see different messages about package compatibility between `dbt-autofix` and v2 warnings. Here's why: * dbt v2 warnings are emitted based on a package's `require-dbt-version` and whether `require-dbt-version` contains `2.0.0`. * Some packages are already v2-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 v2 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 v2 warnings. Here's an example of a v2 warning in the Studio IDE that says a package isn't compatible with v2 but `dbt-autofix` indicates it is compatible: ```text dbt1065: Package 'dbt_utils' requires dbt version [>=1.30,<2.0.0], but current version is 2.0.0. This package may not be compatible with your dbt version. dbt(1065) [Ln 1, Col 1] ``` Report incorrect code ### 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: ```yaml packages: - package: dbt-labs/dbt_utils version: 1.0.0 - package: dbt-labs/codegen version: 0.9.0 ``` Report incorrect code ### Step 2: Check compatibility and find the latest package versions Review [the dbt package hub](https://hub.getdbt.com) to see verified dbt v2-compatible packages by checking that the `require-dbt-version` configuration includes `2.0.0` or higher. Refer to [package support](../docs/dbt/supported-features.md#package-support) for more information. For packages that aren't dbt v2-compatible: * Visit the package's GitHub repository. * Check the README or recent releases for dbt v2 compatibility information. * Look for issues or discussions about dbt v2 support. For each package, find the most recent version: * Visit [dbt Hub](https://hub.getdbt.com) 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: ```yaml packages: - package: dbt-labs/dbt_utils version: [">=1.0.0", "<3.0.0"] # Gets latest 1.x or 2.x version ``` Report incorrect code ### 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: ```yaml packages: - package: dbt-labs/dbt_utils version: 0.9.6 - package: dbt-labs/codegen version: 0.9.0 ``` Report incorrect code After update: ```yaml packages: - package: dbt-labs/dbt_utils version: [">=1.0.0", "<2.0.0"] - package: dbt-labs/codegen version: [">=0.12.0", "<1.0.0"] ``` Report incorrect code ### Step 4: Install updated packages After updating your package versions, install them: 1. In the Studio IDE command line, run: ```bash dbt deps --upgrade ``` Report incorrect code 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: ```bash dbt run --select tag:daily ``` Report incorrect code 2. Run your tests to catch any breaking changes (exact command may vary): ```bash dbt test ``` Report incorrect code 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 dbt v2 compatibility". 3. Click **Commit and sync**. ## Update your jobs Use the dbt v2 readiness panel to validate your jobs against dbt v2 and fix any issues you find. For jobs that are eligible for dbt v2 in the readiness experience, **Run once on dbt v2** is replaced by a **Debug on dbt v2** dropdown in the eligibility banner or modal. Use a debug option when you want to inspect or fix issues interactively in Studio IDE. Use **Run once on dbt v2** when you want to validate execution behavior in a deployment context. ### Review your jobs The readiness panel shows how many jobs are ineligible for dbt v2 or have an unknown eligibility status. If you don't see eligibility messaging, ask an account admin to enable **dbt v2 readiness & upgrade features** in [Account settings](../docs/platform/account-settings.md). For setup steps, refer to [Enable dbt v2 readiness features](./prepare-v2-upgrade.md?step=3). 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](/img/v2/review-jobs.png?v=2 "Shortcut to review your jobs from the readiness panel")](#)Shortcut to review your jobs from the readiness panel 2. Find the dbt v2 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 v2 eligible.](/img/v2/job-eligibility.png?v=2 "Take action on your jobs to make them v2 eligible.")](#)Take action on your jobs to make them v2 eligible. 3. Click **Debug on dbt v2** and choose one of the following: * [Debug in Studio](#debug-in-studio) * [Debug in Studio with dbt Wizard](#debug-in-studio-with-dbt-wizard) * [Run once on dbt v2](#run-once-on-fusion) #### Debug in Studio In the Studio IDE, run dbt v2 in your development environment to review project warnings and errors: 1. Click **Debug in Studio**. dbt sets your user-level `DBT_DEVELOP_CORE_VERSION` environment variable to `latest-fusion`, then opens the Studio IDE with the **Problems** tab selected. [![Running v2 in development](/img/v2/v2-ide.png?v=2 "Running v2 in development")](#)Running v2 in development 2. Review the warnings or errors in the **Problems** tab. 3. Fix the issues directly or run the [autofix tool](../docs/platform/studio-ide/autofix-deprecations.md). 4. When the project runs with no warnings or errors, commit and publish your changes. 5. After you merge the changes, wait for the job to run again or run it manually. To revert the `latest-fusion` override, use the dbt version control in Studio IDE or update the **dbt version** under **User development settings** in [Account settings](../docs/platform/account-settings.md) → **Credentials**. For more details, refer to [Override dbt version](../docs/dbt-versions/upgrade-dbt-platform-version.md#override-dbt-version). #### Debug in Studio with dbt Wizard [Beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") If you have access to [dbt Wizard](../docs/dbt-ai/wizard-ide.md) with [AI features](../docs/platform/manage-dbt-ai.md) enabled, you can use the [dbt v2 migration workflow](../docs/dbt-ai/wizard-ide.md#fusion-migration-workflow) skill. This skill can help you fix compatibility errors directly from the Studio IDE using dbt Wizard — no manual log investigation needed. It classifies every error, applies validated fixes automatically, and surfaces what's blocked. info The dbt v2 migration workflow is accessible through the dbt Wizard in the Studio IDE. If you're using VS Code or the dbt platform CLI, use the [autofix tool](https://docs.getdbt.com/guides/dbt-package-compat?step=4) 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 dbt v2 eligibility** toggle in the job list. 2. In the **dbt v2 eligibility unknown for this job** pop-up, click **Debug in Studio with dbt Wizard**. 3. dbt redirects you to the Studio IDE and sets your personal development environment to dbt v2. 4. dbt Wizard opens and automatically triggers the dbt v2 migration skill with this prompt: ```text I need help fixing dbt v2 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. ``` Report incorrect code 5. Review and approve dbt Wizard's permission requests so it can run the commands it needs. 6. The dbt Wizard 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 dbt v2. [![The Developer Agent's v2 migration workflow triaging and fixing v2 compatibility errors in the Studio IDE.](/img/docs/dbt-platform/v2-migration-workflow.gif?v=2 "The Developer Agent's v2 migration workflow triaging and fixing v2 compatibility errors in the Studio IDE.")](#)The Developer Agent's v2 migration workflow triaging and fixing v2 compatibility errors in the Studio IDE. #### Run once on dbt v2 When you are confident a job is ready for dbt v2, you can run it once on the engine without changing environment-wide settings. **Run once on dbt v2** can be temporarily unavailable while a dbt v2 run request is already pending. 1. Click **Run once on dbt v2**. 2. The job window opens and dbt runs the job on dbt v2 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.](/img/v2/eligibility-status.png?v=2 "Override the eligibility status of a successful job.")](#)Override the eligibility status of a successful job. Congratulations! You have validated dbt v2 eligibility for your jobs. [![Your job is now ready for v2!](/img/v2/v2-eligible.png?v=2 "Your job is now ready for v2!")](#)Your job is now ready for v2! ## What's next? With limitations identified and addressed, you've completed all the preparation steps. Your project is now ready to upgrade to dbt v2! Check out [Part 2: Making the move](./upgrade-to-v2.md)