Install the dbt VS Code extension Preview

The dbt extension for VS Code and Cursor, powered by the dbt Fusion Engine, streamlines dbt development workflows.

Prerequisites​

To use the extension, you must meet the following prerequisites:

Installation instructions​

In VS Code:

1. Navigate to the Extensions tab of your editor and search for dbt. Locate the extension from the publisher dbtLabsInc or dbt Labs Inc. Click Install.
   Search for the extension
2. Open a dbt project in your VS Code environment if you haven't already. Make sure it is added to your current workspace. If you see a dbt Extension label in your editor's status bar, then the extension has installed successfully. You can hover over this dbt Extension label to see diagnostic information about the extension.
   If you see the 'dbt Extension` label, the extension is activated
3. Once the dbt extension is activated, it will automatically begin downloading the correct dbt Language Server for your operating system.
   The dbt Language Server will be installed automatically
4. If the dbt Fusion engine is not already installed on your machine, the extension will prompt you to download and install it. Follow the steps shown in the notification to complete the installation.
   Follow the prompt to install the dbt Fusion engine
5. Run the VS Code extension upgrade tool to ensure your dbt project is Fusion ready and help you fix any errors and deprecations.
6. You're all set up! See about the dbt extension for more information on how to use the dbt extension.
   Showing lineage and compiled code in the extension

Getting started​

Once the dbt VS Code extension has been installed in your environment, the dbt logo will appear on the sidebar. From here, you can access workflows to help you get started, offers information about the extension and your dbt project, and provides helpful links to guide you. For more information, see the the dbt extension menu documentation.

To get started with the extension:

1. From the sidebar menu, click the dbt logo to open the menu and expand the Get started section.
2. Click the dbt Walkthrough status bar to view the welcome screen.
   dbt VS Code extension welcome screen.
3. Click through the items to get started with the extension:
   • Open your dbt project: Launches file explorer so you can select the dbt project you want to open with Fusion.
   • Check Fusion compatibility: Runs the Fusion upgrade workflows to bring your project up-to-date.
   • Explore features: Opens the documentation so you can learn more about all the extension has to offer.
   • Register: Launches the registration workflow so you can continue to use the extension beyond the trial period.

Upgrade to Fusion​

The dbt extension provides a built-in upgrade tool to walk you through the process of configuring Fusion and updating your dbt project to support all of its features and fix any deprecated code. To start the process:

1. From the VS Code sidebar menu, click the dbt logo.

2. In the resulting pane, open the Get started section and click the Get started button.

   The dbt extension help pane and upgrade assistant.

You can also manually start this process by opening a CLI window and running:

dbt init --fusion-upgrade

This will start the upgrade tool and guide you through the Fusion upgrade with a series of prompts:

• Do you have an existing dbt platform account?: If you answer Y, you will be given instructions for downloading your dbt platform profile to register the extension. An N answer will skip to the next step.

• Ready to run a dbtf init? (If there is no profiles.yml file present): You will go through the dbt configuration processes, including connecting to your data warehouse.

• Ready to run a dbtf debug? (If there is an existing profiles.yml file): Validates that your project is configured correctly and can connect to your data warehouse.

• Ready to run a dbtf parse?: Your dbt project will be parsed to check for compatibility with Fusion.

  • If any issues are encountered during the parsing, you'll be given the option to run the dbt-autofix tool to resolve the errors. If you opt to not run the tool during the upgrade processes, you can always run it later or manually fix any errors. However, the upgrade tool cannot continue until the errors are resolved.
    AI Agents

    There are cases where dbt-autofix may not resolve all errors and requires manual intervention. For those cases, the dbt-autofix tool provides an AI Agents.md file to enable AI agents to help with migration work after dbt-autofix has completed its part.

• Ready to run a ‘dbtf compile -static-analysis off’? (Only runs once the parse passes): Compiles your project without any static analysis, mimicking dbt Core. This compile only renders Jinja into SQL, so Fusion's advanced SQL comprehension is temporarily disabled.

• Ready to run a ‘dbtf compile’?: Compiles your project with full Fusion static analysis. It checks that your SQL code is valid in the context of your warehouse's tables and columns.

  The message received when you have completed upgrading your project to the dbt Fusion engine.

Once the upgrade is completed, you're ready to dive into all the features that the dbt Fusion Engine has to offer!

Register the extension​

Users must complete registration within 14 days of installing the dbt extension. There are two ways to register:

• Users without an existing dbt account can register quickly and easily through an online registration form. For the initial installation, you only need to provide your name and email address to complete the registration. Subsequent installations will require you to complete the entire dbt account registration process to use the extension.
• Users with an existing dbt account can connect their account using a dbt_cloud.yml credentials file.

The VS Code extension is free for organizations for up to 15 users.

New user registration​

If you do not already have a dbt account, you'll need to get registered. This only takes a minute!

1. Click the registration prompt in your editor.
   The extension registration prompt in VS Code.
2. Accept any prompts to open the link in your browser.
3. Fill out the registration form, then click Continue.
   The extension registration page in the browser.
4. You will receive an email with a verification link. Once you click it, your registration is complete!

Accessing your dbt account​

Registering to use the dbt extension makes it easy to create a full dbt account. You can follow these steps to finish setting up your account (Note: This is not required to use the dbt extension).

1. Navigate to us1.dbt.com and click Forgot password?.
2. Enter the email address you used for your dbt extension registration and click Continue.
3. Check your email for a verification link and follow the password reset instructions to set a password for your account.

Now that you have activated your dbt developer account, you can access features of the dbt platform. You can also re-download your registration key using the steps outlined in Register with an existing dbt account if you need to set up the dbt extension on a new machine.

Register with an existing dbt account​

If you already have a dbt account, you do not need to re-register to use the dbt extension. The dbt extension can authenticate with the dbt platform using a dbt_cloud.yml file. If this file is present in your ~/.dbt/ folder, then the registration flow will automatically attempt to use this file during registration. If you do not have a ~/.dbt/dbt_cloud.yml file downloaded, refer to the following instructions:

Troubleshooting​

If you run into any issues, check out the troubleshooting section below.

dbt-cloud:
project-id: 12345 # Required

More information about Fusion​

Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations:

• About the dbt Fusion engine
• About the dbt extension
• New concepts in Fusion
• Supported features matrix
• Installing Fusion CLI
• Installing VS Code extension
• Fusion release track
• Quickstart for Fusion
• Upgrade guide
• Fusion licensing