Quickstart for the dbt Fusion engine

Introduction​

The dbt Fusion Engine is a powerful new approach to classic dbt ideas! Completely rebuilt from the ground up in Rust, Fusion lets you compile and run your dbt projects faster than ever — often in seconds.

This quickstart guide will get you from zero to running your first dbt project with Fusion + VS Code. By the end, you’ll have:

• A working dbt project (jaffle_shop) built with the dbt Fusion Engine
• The dbt VS Code extension installed and connected
• The ability to preview, compile, and run dbt commands directly from your IDE

About the dbt Fusion engine​

Fusion and the features it provides are available in multiple environments:

Tip: Read more about the dbt Fusion Engine to understand what’s new, what’s changed, and what’s deprecated.

Prerequisites​

To take full advantage of this guide, you'll need to meet the following prerequisites:

• You should have a basic understanding of dbt projects, git workflows, and data warehouse requirements.
• Make sure you're using a supported adapter and authentication method:
   BigQuery

  • Service Account / User Token
  • Native OAuth
  • External OAuth
  • Required permissions
   Databricks

  • Service Account / User Token
  • Native OAuth
   Redshift

  • Username / Password
   Snowflake

  • Username / Password
  • Native OAuth
  • External OAuth
  • Key pair using a modern PKCS#8 method
  • MFA
• You need a macOS (Terminal), Linux, or Windows (Powershell) machine to run the dbt Fusion Engine.
• You need to have Visual Studio Code installed. The Cursor code editor will also work, but these instructions will focus on VS Code.
• You need admin or install privileges on your machine.

What you’ll learn​

By following this guide, you will:

• Set up a fully functional dbt environment with an operational project
• Install and use the dbt Fusion Engine + dbt VS Code extension
• Run dbt commands from your IDE or terminal
• Preview data, view lineage, and write SQL faster with autocomplete, and more!

You can learn more through high-quality dbt Learn courses and workshops.

Installation​

It's easy to think of the dbt Fusion Engine and the dbt extension as two different products, but they're a powerful combo that works together to unlock the full potential of dbt. Think of the dbt Fusion Engine as exactly that — an engine. The dbt extension and VS Code are the chassis, and together they form a powerful vehicle for transforming your data.

The following are the essential steps from the dbt Fusion Engine and extension installation guides:

Verify the dbt Fusion Engine installation​

1. After installation, open a new command-line window to confirm that Fusion was installed correctly by checking the version.

   dbtf --version
   
2. You should see output similar to the following:

   dbt-fusion 2.0.0-preview.45
   

Install the dbt VS Code extension​

The dbt VS Code extension is available in the Visual Studio extension marketplace. Download it directly from your VS Code editor:

1. Navigate to the Extensions tab of VS Code (or Cursor).
2. Search for dbt and choose the one from the publisher dbt Labs Inc.
   Search for the extension
3. Click Install.
4. When the prompt appears, you can register the extension now or skip it (you can register later). You can also check out our installation instructions to come back to it later.
5. Confirm you've installed the extension by looking for the dbt Extension label in the status bar. If you see it, the extension was installed successfully!
   Verify installation in the status bar.

Initialize the Jaffle Shop project​

Now let's create your first dbt project powered by Fusion!

1. Run dbt init to set up an example project and configure a database connection profile.

   • If you do not have a connection profile that you want to use, start with dbt init and use the prompts to configure a profile:

   • If you already have a connection profile that you want to use, use the --skip-profile-setup flag then edit the generated dbt_project.yml to replace profile: jaffle_shop with profile: <YOUR-PROFILE-NAME>.

     dbtf init --skip-profile-setup
     

   • If you created new credentials through the interactive prompts, init automatically runs dbtf debug at the end. This ensures the newly created profile establishes a valid connection with the database.

2. Change directories into your newly created project:

   cd jaffle_shop
   

3. Build your dbt project (which includes creating example data):

   dbtf build
   

This will:

• Load example data into your warehouse
• Create, build, and test models
• Verify your dbt environment is fully operational

Explore with the dbt VS Code extension​

The dbt VS Code extension compiles and builds your project with the dbt Fusion Engine, a powerful and blazing fast rebuild of dbt from the ground up.

Want to see Fusion in action? Check out the following video to get a sense of how it works:

Now that your project works, open it in VS Code and see Fusion in action:

1. In VS Code, open the View menu and click Command Palette. Enter Workspaces: Add Folder to Workspace.
2. Select your jaffle_shop folder. If you don't add the root folder of the dbt project to the workspace, the dbt language server (LSP) will not run. The LSP enables features like autocomplete, hover info, and inline error highlights.
3. Open a model file to see the definition for the orders model. This is the model we'll use in all of the examples below.

       models/marts/orders.sql
   
4. Locate Lineage and Query Results in the lower panel, and the dbt icon in the upper right corner next to your editor groups. If you see all of these, the extension is installed correctly and running!
   The VS Code UI with the extension running.

Now you're ready to see some of these awesome features in action!

• Preview data and code
• Navigate your project with lineage tools
• Use the power of SQL understanding
• Speed up common dbt commands

Preview data and code​

Gain valuable insights into your data transformation during each step of your development process. You can quickly access model results and underlying data structures directly from your code. These previews help validate your code step-by-step.

1. Locate the table icon for Preview File in the upper right corner. Click it to preview results in the Query Results tab.
   Preview model query results.
2. Click Preview CTE above orders as ( to preview results in the Query Results tab.
   Preview CTE query results.
3. Locate the code icon for Compile File in between the dbt and the table icons. Clicking this icon opens a window with the compiled version of the model.
   Compile File icon.
   Compile File results.

Navigate your project with lineage tools​

Almost as important as where your data is going is where it's been. The lineage tools in the extension let you visualize the lineage of the resources in your models as well as the column-level lineage. These capabilities deepen your understanding of model relationships and dependencies.

1. Open the Lineage tab to visualize the model-level lineage of this model.
   Visualizing model-level lineage.
2. Open the View menu, click Command Palette and enter dbt: Show Column Lineage to visualize the column-level lineage in the Lineage tab.
   Show column-level lineage.

Use the power of SQL understanding​

Code smarter, not harder. The autocomplete and context clues help avoid mistakes and enable you to write fast and accurate SQL. Catch issues before you commit them!

1. To see Autocomplete in action, delete ref('stg_orders'), and begin typing ref(stg_ to see the subset of matching model names. Use up and down arrows to select stg_orders.
   Autocomplete for a model name.
2. Hover over any * to see the list of column names and data types being selected.
   Hovering over * to see column names and data types.

Speed up common dbt commands​

Testing, testing... is this mic on? It is and it's ready to execute your commands with blazing fast speeds! When you want to test your code against various dbt commands:

1. The dbt icon in the top right opens a list of extension-specific commands:
   Select a command via the dbt icon.
2. Opening the View menu, clicking the Command Palette, and entering >dbt: in the command bar shows all the new commands that are available.
   dbt commands in the command bar.

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