How Lightdash Connects to Your dbt Project

Lightdash reads a dbt project’s compiled output and generates SQL queries that run directly against the warehouse. It does not import data or maintain its own transformation logic. The dbt project functions as the semantic layer; the BI layer generates itself from it.

The connection mechanism determines how quickly changes propagate, how much manual intervention is required, and where compilation happens.

The Three Connection Mechanisms

Git Repository Integration

The simplest path for teams already using a remote Git host. Lightdash connects directly to GitHub, GitLab, Azure DevOps, or Bitbucket using standard OAuth or token authentication.

When a connection is established:

Lightdash reads the repository at the configured branch
Compiles the dbt project server-side
Generates the Explore UI from the compiled output

The compilation happens in Lightdash’s environment, which means Lightdash needs access to your dbt packages and any dependencies your project pulls in via dbt deps. For most projects this works cleanly. For projects with private package dependencies, you need to configure authentication separately.

Changes made in the repository don’t propagate automatically — you trigger a refresh manually from the Lightdash UI, or combine this mechanism with the CI/CD approach below.

CLI Deployment

The lightdash deploy command pushes a compiled dbt project from a local machine or a CI/CD runner:

# Install the CLI
npm install -g @lightdash/cli

# Authenticate
lightdash login --token <your-api-token>

# Deploy from your dbt project directory
dbt compile && lightdash deploy --project-uuid <uuid>

The key detail: you run dbt compile locally first, then pass the compiled output to lightdash deploy. This means compilation happens in your environment rather than Lightdash’s. If your dbt project has complex macro dependencies, private packages, or environment-specific variable handling, CLI deployment often produces more predictable results than Git integration.

CLI deployment is also the pattern used from within CI/CD pipelines — the distinction between “CLI” and “CI/CD” deployment is more about context than mechanism.

Continuous Deployment via CI/CD (Recommended)

The production-grade approach. A GitHub Actions workflow (or equivalent) runs automatically after every successful merge to the main branch. No manual refresh steps, no possibility of the BI layer falling out of sync with the dbt project.

A minimal GitHub Actions workflow:

name: Deploy to Lightdash
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dbt
        run: pip install dbt-bigquery  # or your warehouse adapter

      - name: Install Lightdash CLI
        run: npm install -g @lightdash/cli

      - name: Compile dbt project
        run: dbt compile
        env:
          DBT_PROFILES_DIR: .
          DBT_TARGET: prod

      - name: Deploy to Lightdash
        run: lightdash deploy --project-uuid ${{ secrets.LIGHTDASH_PROJECT_UUID }}
        env:
          LIGHTDASH_API_KEY: ${{ secrets.LIGHTDASH_API_KEY }}
          LIGHTDASH_URL: ${{ secrets.LIGHTDASH_URL }}

The CI/CD pattern means that merging a pull request updating a model’s YAML — adding a metric, updating a description, adjusting a dimension type — automatically propagates to Lightdash within minutes of merge. The pull request process becomes the governance workflow for both dbt models and BI layer definitions.

What Lightdash Reads from dbt YAML

The compilation output that Lightdash processes contains all the information it needs to build the Explore interface. Three sources drive what appears:

Model columns automatically become dimensions. Every column declared in a model’s YAML file is a potential dimension. No annotation required. The column’s description from dbt flows through as hover text in the Explore view.

The meta: block is where Lightdash-specific configuration lives. On dbt v1.9 and earlier, meta: sits directly under the column or model. On v1.10+ with the Fusion engine, it wraps inside a config: block.

dbt descriptions become the documentation layer that end users see. This is the mechanism by which documentation effort in dbt pays off in the BI layer without any duplication. Write descriptions once, in version control, and they surface wherever the data is consumed.

A minimal example that shows all three elements:

models:
  - name: mrt__sales__orders
    description: "One row per order. Excludes test accounts and internal orders."
    meta:
      primary_key: order__id
      joins:
        - join: mrt__sales__customers
          sql_on: ${mrt__sales__orders.order__customer_id} = ${mrt__sales__customers.customer__id}
          relationship: many-to-one
      metrics:
        order__average_revenue:
          type: number
          sql: ${order__total_revenue} / NULLIF(${order__orders}, 0)
          format: '[$€]#,##0.00'
    columns:
      - name: order__id
        description: "Unique order identifier"
        meta:
          metrics:
            order__orders:
              type: count_distinct
      - name: order__revenue
        description: "Order total in EUR, after discounts"
        meta:
          dimension:
            type: number
            hidden: true  # available for metrics, invisible as raw dimension
          metrics:
            order__total_revenue:
              type: sum
              format: '[$€]#,##0.00'

When a user selects dimensions, metrics, and filters in the Explore UI, Lightdash generates optimized SQL with the appropriate JOINs, GROUP BYs, and filter clauses. The query executes against the connected warehouse directly. Lightdash doesn’t cache or store query results (caching is a Cloud Pro feature).

Supported Warehouses

Lightdash supports: BigQuery, Snowflake (OAuth, password, or private key auth), Redshift, Databricks, PostgreSQL, Trino, and ClickHouse.

The warehouse connection is configured separately from the dbt project connection. Lightdash needs direct query access to the warehouse to run the SQL it generates. It does not route queries through dbt — dbt is only used at compile time to generate the schema that Lightdash reads.

The Meta Tag as Extension Point

The meta: block is the entire surface area of Lightdash’s YAML configuration. Everything that makes a Lightdash Explore more useful than a raw table view lives there: metrics, joins, group labels, display formatting, dimension types, hidden flags, and access controls.

The deliberate constraint is that meta: sits in the same files where you already document your dbt models. There’s no separate Lightdash configuration file to maintain alongside your schema.yml. The BI layer configuration is in the same place as the model documentation, reviewed in the same pull requests, governed by the same team.

This is what distinguishes Lightdash’s approach from tools that maintain parallel modeling layers. For more on the specific configuration syntax, see Lightdash Dimension Configuration in dbt YAML for dimension configuration and Lightdash Metric Types and Definition Syntax for metric definition patterns. For the broader question of why dbt is becoming the foundation that BI tools read from, see dbt as the Center of Gravity for BI.