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.
Migration
-
Upgrade your Python package:
pip install --upgrade hashboard-cli
-
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. -
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 runninghb init
, and then usehb build
, which will automatically build any dbt models that havehashboard
meta key.