Skip to main content
lightdash deploy pushes your local dbt or native Lightdash YAML models to Lightdash. Use it to publish local changes, or use lightdash refresh to compile the files already committed to your connected repository. For native models, follow the Lightdash YAML deployment steps; the profiles and targets in the CLI examples below apply to dbt.

​
Before you deploy: A quick word of caution

lightdash deploy pushes directly to your production project.For dbt projects, this command uses your local dbt profile (from your profiles.yml). If your default target points to a dev or staging environment, lightdash deploy will overwrite your production semantic layer with that configuration, breaking dashboards for all users.If you’re working locally, use lightdash preview instead. It creates a temporary, isolated project that won’t affect production.
For a safer, scalable approach to deploying and previewing changes, use CI/CD. This allows you to:
  • Spin up Lightdash preview environments for each PR
  • Deploy production changes consistently using shared, secure credentials
  • Avoid accidentally pointing to the wrong target in your local profile
Check out our guide to setting up CI/CD workflow

​
Option 1: Deploy via the CLI

Basic usage:
By default, this will:
  • Use your local dbt profile for the connection
  • Push the current state of your local dbt project files (including uncommitted changes or code from your active branch) to the authenticated Lightdash project
  • Trigger a re-compile and refresh of your Lightdash project
If your dbt project uses different profiles or targets for dev and prod, you can specify which profile to use:
Be careful. If your local prod profile isn’t properly pointing to your production database, this can result in incorrect connections (e.g. accidentally deploying to a dev dataset). Without a selection flag, lightdash deploy compiles every model in your dbt project, and a model with no columns in its YAML shows up as an errored explore reporting No dimensions available. To deploy only the models you use in Lightdash, for example when your project also contains upstream models you don’t query, pass --select, --exclude or --selector. lightdash preview and lightdash start-preview take the same flags. See dbt node selection.

​
Use strict compilation

Lightdash uses partial compilation by default. Field, join, and set-validation failures that can be isolated are reported as warnings so the rest of the explore stays usable; failures that cannot be isolated can still produce errors. Add --no-partial-compilation to report the failures that partial compilation would otherwise isolate as errors instead. It doesn’t promote unrelated, non-blocking warnings — other generic compilation warnings stay non-blocking. If your project uses physical column references such as ${TABLE}.order_id, add --validate-warehouse-columns to check supported unquoted references with warehouse queries that return no rows. It’s opt-in because it sends those queries; whether your warehouse scans or bills for them is warehouse-dependent, and the check needs warehouse credentials and the warehouse catalog. Warehouse-column errors are reported whether partial compilation is on or off. See the CLI compilation options for the supported reference syntax and every skip condition. For the strictest deploy, combine both flags:
Do not combine --ignore-errors with this strict CI pattern — --ignore-errors lets a deployment continue after compilation errors, which defeats the check.

​
Troubleshoot warehouse connection errors

To read column types from the warehouse catalog, lightdash deploy connects to your warehouse directly from the machine running the CLI, such as your laptop or a CI runner, using the credentials in your profiles.yml. A warehouse connection timeout during deploy, such as Connection terminated due to connection timeout, means that machine can’t reach the warehouse. Check its network path: VPN, firewall, or the warehouse’s IP allowlist. lightdash diagnostics doesn’t test this connection, so it can pass while deploy fails. To deploy without connecting for the catalog, add --skip-warehouse-catalog. Lightdash then uses the column types declared in your YAML.

​
Option 2: Safely refresh metadata using lightdash refresh

To pull committed changes from the configured branch of your project’s Git repository, run:
Unlike deploy, this:
  • Uses the connection saved in Lightdash
  • Compiles the repository using the project’s selected semantic layer format
  • Leaves your local files and dbt profile out of the refresh
You can also do this directly from the Lightdash UI: Click Refresh dbt for a dbt project or Refresh models for a native YAML project. This gives the same result as running lightdash refresh.
The Refresh dbt button highlighted at the top of the explore view, above the filters bar