v2 to v3 migration guide

Version 3 of the Hashboard CLI launched in September 2024. Below is a guide to upgrading from Version 2 to Version 3.

Major changes:

Creating and applying builds

There are no longer separate “Preview builds” and “Deploy builds”. Instead, you create a “build” once, which you can preview and then, if desired, apply directly. Applying a build is instantaneous.

Builds are partial by default

When creating a build with the v2 CLI, resources that were previously deployed with code but no longer present were treated as deletions.

In v3, Hashboard will only process changes for the files you’ve provided. For instance, you can choose to create a build that only includes your dashboards, even if you have yml files for other resources.

$ ls
models		explorations			dashboards
 
$ hb build dashboards/*  # Creates a build scoped just to your dashboards

Note that builds can still delete downstream content. For example, if you update a model and remove one of its attributes, Explorations which depend on that attribute may be slated for removal, even if they are not in the build.

Rebuilding all code-controlled resources in the project is still available by supplying a --full_rebuild flag:

$ hb build . --full-rebuild  # Will delete any missing Hashboard resources that
                             # were previously deployed with code

Project root file

The v2 CLI was sensitive to where you ran it (your current working directory) relative to your yml files. If you didn’t run hb from the right location, your resource IDs might unexpectedly change.

The v3 CLI introduces a hb init command, which creates a .hbproject file in your filesystem. This file is to be placed at the root of your Hashboard project. It ensures that your resource identities are stable whenever you run a Hashboard command within that directory or any of its subdirectories.

Additionally, for dbt users, the .hbproject file can define the root of your dbt project. When present, we will always import your dbt models into your builds, so you no longer need to remember to include the --dbt flag.

We will continue adding additional useful metadata into the .hbproject file over time.

dbt flags

The v2 CLI consumed an arbitrary number of dbt flags that would be passed directly to the dbt parse step on build. In v3 of the CLI these flags should be set as environment variables when executing Hashboard commands.

For example hb preview --target=prod in v2 would be run as DBT_TARGET=prod hb build in v3 of the CLI. For a full list of flag and environment variable substitutes please refer to the dbt flag documentation (opens in a new tab).

Migration

1. Upgrade your Python package: pip install --upgrade hashboard-cli

2. Run hb init at the root of your Hashboard project files, specifying --dbt-root=... if you have dbt-based models. Commit the resulting .hbproject file into your git repository.

3. In your scripts / CI actions, migrate commands as follows:

   Previous command	New command
   hb preview (filepath)	hb build (filepath) Include the --full_rebuild flag if you want to delete missing resources.
   hb deploy (filepath)	If the build was already created for previewing: hb build apply If no build has been created yet: hb build (filepaths) && hb build apply (--no-confirm) Include the --full_rebuild flag if you want to delete missing resources.
   hb preview/deploy --dbt	Set --dbt-root when running hb init, and then use hb build, which will automatically build any dbt models that have hashboard meta key.