From 17eda1771e689df7ed67cf8f31e84c4b7b1c4efe Mon Sep 17 00:00:00 2001 From: Cloudy Date: Thu, 12 Nov 2026 05:27:05 +0000 Subject: [PATCH 1/4] Add dbt versions explainer to Upgrading dbt --- integrations/connect-project.mdx | 2 +- integrations/dbt/upgrading.mdx | 26 ++++++++++++++++++++++---- 2 files changed, 23 insertions(+), 5 deletions(-) diff --git a/integrations/connect-project.mdx b/integrations/connect-project.mdx index 8ec9ab14e..ee20b957e 100644 --- a/integrations/connect-project.mdx +++ b/integrations/connect-project.mdx @@ -1504,7 +1504,7 @@ Then scroll down to the dbt project section: The dbt connection section of Lightdash project settings, with type GitHub, OAuth authorization, and repository, dbt version, and branch fields -The **dbt version** field sets the dbt Core 1.x version Lightdash uses when it compiles your project. Lightdash supports dbt Core 1.4 to 1.12. The default, **latest**, uses the newest version Lightdash supports, currently 1.12. If a refresh fails with a dbt compile error and the project is pinned to an older version, choose a newer version, or **latest**, and refresh again. `lightdash deploy` and `lightdash preview` compile with the dbt you have installed, so for those, upgrade dbt locally. The list has no dbt Core v2 (Fusion) option: for a Fusion project, keep **latest** and keep the project compatible with dbt Core 1.10 or later, as described in [Moving to dbt Core v2 (Fusion)](/integrations/dbt/upgrading#moving-to-dbt-core-v2-fusion). +The **dbt version** field sets the dbt Core 1.x version Lightdash uses when it compiles your project. Lightdash supports dbt Core 1.4 to 1.12. The default, **latest**, uses the newest version Lightdash supports, currently 1.12. If a refresh fails with a dbt compile error and the project is pinned to an older version, choose a newer version, or **latest**, and refresh again. `lightdash deploy` and `lightdash preview` compile with the dbt you have installed, so for those, upgrade dbt locally. The list has no dbt v2 option, whether dbt v2 or dbt OSS v2: for a dbt v2 project, keep **latest** and keep the project compatible with dbt Core 1.10 or later, as described in [dbt versions](/integrations/dbt/upgrading#dbt-versions) and [Moving to dbt Core v2 (Fusion)](/integrations/dbt/upgrading#moving-to-dbt-core-v2-fusion). Pick your connection type and follow the guide below: [GitHub](#github), [GitLab](#gitlab), [Azure DevOps](#azure-devops), [Bitbucket](#bitbucket), [dbt Cloud](#dbt-cloud), or the [CLI](#cli). diff --git a/integrations/dbt/upgrading.mdx b/integrations/dbt/upgrading.mdx index 067aa45ca..0a05144de 100644 --- a/integrations/dbt/upgrading.mdx +++ b/integrations/dbt/upgrading.mdx @@ -3,7 +3,25 @@ title: "Upgrading dbt" description: "What changes in your Lightdash setup when you move between dbt versions" --- -Lightdash reads your dbt project, so a dbt upgrade can change how your semantic layer is declared. Two changes matter: where `meta` and `tags` live as of 1.10, and the Fusion engine that ships as dbt Core v2. +Lightdash reads your dbt project, so a dbt upgrade can change how your semantic layer is declared. Two changes matter: where `meta` and `tags` live as of 1.10, and the move to dbt v2, the Rust rewrite of dbt that was called Fusion. + +## dbt versions + +"dbt" now covers four groups of releases. Find yours, then see what Lightdash does with it. + +- dbt v2+ is what used to be called Fusion: the Rust rewrite of dbt plus the features powered by dbt Cloud, which you reach by logging in from the CLI. +- dbt OSS v2+ is the Rust rewrite alone, released under Apache 2.0. It continues what used to be called dbt Core. It prints itself as `dbt-oss` in `dbt --version`, for example `dbt-oss 2.0.11`. +- dbt v1.10 to v1.13 are the last modern dbt Core releases, and any later v1.* release is the same line. Only maintenance updates ship on v1.* from here, and many teams still run them. Lightdash supports up to v1.12. +- dbt v1.9 and below are older releases. `meta:` sits directly under the model or column in your YAML, which is where Lightdash configs nest. From v1.10, `meta:` moves under a `config:` block, as described in Moving to dbt 1.10 below. + + + "OSS" in a name means a different distribution from plain dbt v2+, even at the same version number. Some features differ a little and some a lot, depending on the feature. Check the distribution that `dbt --version` prints, not only the version number. + + +What Lightdash does with each: + +- Git-connected projects compile with dbt Core 1.x, at the version set in your [project connection settings](/integrations/connect-project#2-import-a-dbt-project). Lightdash supports 1.4 to 1.12, and there is no dbt v2 option. +- The CLI (`lightdash deploy`, `lightdash preview` and `lightdash validate`) uses the dbt installed on your machine, for any of the four groups. The CLI recognizes `dbt-oss 2.x` output from version 3.209.1. Earlier CLI versions fail to detect it, so update the CLI if you run dbt OSS v2. ## Moving to dbt 1.10 @@ -310,9 +328,9 @@ For projects with hundreds of YAML files: ## Moving to dbt Core v2 (Fusion) -The Fusion engine is a rewrite of dbt in Rust, with faster builds, native SQL understanding, and real-time validation. It is not a separate product: **Fusion ships as dbt Core v2**, and it is open source like the Core releases before it. The proprietary parts of dbt live in dbt Cloud, which you reach by logging in from the CLI — the engine itself is not gated. +The Rust rewrite of dbt, called Fusion, has faster builds, native SQL understanding, and real-time validation. It ships as dbt v2 and as dbt OSS v2, which differ as described in [dbt versions](#dbt-versions). The engine itself is not gated: the proprietary parts of dbt live in dbt Cloud, which you reach by logging in from the CLI. -Your SQL and YAML syntax is unchanged. What differs is enforcement: Fusion validates more strictly than earlier Core releases, so a project carrying unresolved deprecation warnings will fail on it. +Your SQL and YAML syntax is unchanged. What differs is enforcement: dbt v2 validates more strictly than earlier Core releases, so a project carrying unresolved deprecation warnings will fail on it. ### Before you upgrade @@ -323,5 +341,5 @@ Your SQL and YAML syntax is unchanged. What differs is enforcement: Fusion valid Check the [dbt Fusion documentation](https://docs.getdbt.com/docs/fusion/about-fusion) for engine-specific behavior and any features still landing. - The Lightdash CLI works with Fusion: `lightdash deploy` and `lightdash preview` compile your project with the dbt you have installed, including Fusion. When Lightdash compiles your project itself, on a [Git connection refresh](/integrations/dbt/projects#git-connection-methods), it uses dbt Core 1.x at the dbt version set in your [project connection settings](/integrations/connect-project#2-import-a-dbt-project). Keep your project compatible with dbt Core 1.10 or later so both paths compile it. + The Lightdash CLI works with dbt v2: `lightdash deploy` and `lightdash preview` compile your project with the dbt you have installed, including dbt v2 and dbt OSS v2. When Lightdash compiles your project itself, on a [Git connection refresh](/integrations/dbt/projects#git-connection-methods), it uses dbt Core 1.x at the dbt version set in your [project connection settings](/integrations/connect-project#2-import-a-dbt-project). Keep your project compatible with dbt Core 1.10 or later so both paths compile it. From b2c5562489355e7f23b0589c227fa2fd472477f6 Mon Sep 17 00:00:00 2001 From: Jake Peterson <5532776+jpetey75@users.noreply.github.com> Date: Thu, 19 Nov 2026 14:34:36 -0600 Subject: [PATCH 2/4] Correct the dbt versions explainer and trim it to a table - Drop the v1.10-1.13 maintenance claim (1.13 is in beta) and the 'engine is not gated' line (dbt v2 is under the dbt Product License) - One table instead of two lists and a callout - Rename the Fusion heading, keep the old anchor Co-Authored-By: Claude Opus 5.5 --- integrations/connect-project.mdx | 2 +- integrations/dbt/upgrading.mdx | 32 +++++++++++++------------------- 2 files changed, 14 insertions(+), 20 deletions(-) diff --git a/integrations/connect-project.mdx b/integrations/connect-project.mdx index ee20b957e..f1b2682b0 100644 --- a/integrations/connect-project.mdx +++ b/integrations/connect-project.mdx @@ -1504,7 +1504,7 @@ Then scroll down to the dbt project section: The dbt connection section of Lightdash project settings, with type GitHub, OAuth authorization, and repository, dbt version, and branch fields -The **dbt version** field sets the dbt Core 1.x version Lightdash uses when it compiles your project. Lightdash supports dbt Core 1.4 to 1.12. The default, **latest**, uses the newest version Lightdash supports, currently 1.12. If a refresh fails with a dbt compile error and the project is pinned to an older version, choose a newer version, or **latest**, and refresh again. `lightdash deploy` and `lightdash preview` compile with the dbt you have installed, so for those, upgrade dbt locally. The list has no dbt v2 option, whether dbt v2 or dbt OSS v2: for a dbt v2 project, keep **latest** and keep the project compatible with dbt Core 1.10 or later, as described in [dbt versions](/integrations/dbt/upgrading#dbt-versions) and [Moving to dbt Core v2 (Fusion)](/integrations/dbt/upgrading#moving-to-dbt-core-v2-fusion). +The **dbt version** field sets the dbt Core 1.x version Lightdash uses when it compiles your project. Lightdash supports dbt Core 1.4 to 1.12. The default, **latest**, uses the newest version Lightdash supports, currently 1.12. If a refresh fails with a dbt compile error and the project is pinned to an older version, choose a newer version, or **latest**, and refresh again. `lightdash deploy` and `lightdash preview` compile with the dbt you have installed, so for those, upgrade dbt locally. The list has no dbt v2 option: for a dbt v2 project, keep **latest** and keep the project compatible with dbt Core 1.10 or later, as described in [Moving to dbt v2](/integrations/dbt/upgrading#moving-to-dbt-v2-fusion). Pick your connection type and follow the guide below: [GitHub](#github), [GitLab](#gitlab), [Azure DevOps](#azure-devops), [Bitbucket](#bitbucket), [dbt Cloud](#dbt-cloud), or the [CLI](#cli). diff --git a/integrations/dbt/upgrading.mdx b/integrations/dbt/upgrading.mdx index 0a05144de..8e975a9ff 100644 --- a/integrations/dbt/upgrading.mdx +++ b/integrations/dbt/upgrading.mdx @@ -3,25 +3,17 @@ title: "Upgrading dbt" description: "What changes in your Lightdash setup when you move between dbt versions" --- -Lightdash reads your dbt project, so a dbt upgrade can change how your semantic layer is declared. Two changes matter: where `meta` and `tags` live as of 1.10, and the move to dbt v2, the Rust rewrite of dbt that was called Fusion. +Lightdash reads your dbt project, so a dbt upgrade can change how your semantic layer is declared. Two changes matter: where `meta` and `tags` live as of 1.10, and the move to dbt v2 (formerly Fusion). ## dbt versions -"dbt" now covers four groups of releases. Find yours, then see what Lightdash does with it. +dbt comes in three forms, and Lightdash compiles each one differently. -- dbt v2+ is what used to be called Fusion: the Rust rewrite of dbt plus the features powered by dbt Cloud, which you reach by logging in from the CLI. -- dbt OSS v2+ is the Rust rewrite alone, released under Apache 2.0. It continues what used to be called dbt Core. It prints itself as `dbt-oss` in `dbt --version`, for example `dbt-oss 2.0.11`. -- dbt v1.10 to v1.13 are the last modern dbt Core releases, and any later v1.* release is the same line. Only maintenance updates ship on v1.* from here, and many teams still run them. Lightdash supports up to v1.12. -- dbt v1.9 and below are older releases. `meta:` sits directly under the model or column in your YAML, which is where Lightdash configs nest. From v1.10, `meta:` moves under a `config:` block, as described in Moving to dbt 1.10 below. - - - "OSS" in a name means a different distribution from plain dbt v2+, even at the same version number. Some features differ a little and some a lot, depending on the feature. Check the distribution that `dbt --version` prints, not only the version number. - - -What Lightdash does with each: - -- Git-connected projects compile with dbt Core 1.x, at the version set in your [project connection settings](/integrations/connect-project#2-import-a-dbt-project). Lightdash supports 1.4 to 1.12, and there is no dbt v2 option. -- The CLI (`lightdash deploy`, `lightdash preview` and `lightdash validate`) uses the dbt installed on your machine, for any of the four groups. The CLI recognizes `dbt-oss 2.x` output from version 3.209.1. Earlier CLI versions fail to detect it, so update the CLI if you run dbt OSS v2. +| Release | What it is | How Lightdash compiles it | +| --- | --- | --- | +| **dbt Core 1.x** | The Python releases. From 1.10, `meta` and `tags` move under `config:`, as described below. | Git connection refreshes use the [**dbt version**](/integrations/connect-project#2-import-a-dbt-project) set for the project. The CLI uses the version you have installed. | +| **dbt v2** | The Rust rewrite formerly called Fusion, under the dbt Product License. | CLI only. Git-connected projects have no v2 option. | +| **dbt OSS v2** | The Apache 2.0 build of the Rust rewrite. Some features differ from dbt v2 at the same version. `dbt --version` prints `dbt-oss`. | CLI only, from Lightdash CLI 3.209.1. | ## Moving to dbt 1.10 @@ -326,11 +318,13 @@ For projects with hundreds of YAML files: 2. Use the `-o` flag to organize transformed files by directory 3. Process files in batches to make review manageable -## Moving to dbt Core v2 (Fusion) + + +## Moving to dbt v2 (Fusion) -The Rust rewrite of dbt, called Fusion, has faster builds, native SQL understanding, and real-time validation. It ships as dbt v2 and as dbt OSS v2, which differ as described in [dbt versions](#dbt-versions). The engine itself is not gated: the proprietary parts of dbt live in dbt Cloud, which you reach by logging in from the CLI. +dbt v2, the Rust rewrite formerly called Fusion, has faster builds, native SQL understanding, and real-time validation. It ships as dbt v2 and dbt OSS v2; see [dbt versions](#dbt-versions). -Your SQL and YAML syntax is unchanged. What differs is enforcement: dbt v2 validates more strictly than earlier Core releases, so a project carrying unresolved deprecation warnings will fail on it. +Your SQL and YAML syntax is unchanged. What differs is enforcement: dbt v2 validates more strictly than dbt Core 1.x, so a project carrying unresolved deprecation warnings will fail on it. ### Before you upgrade @@ -341,5 +335,5 @@ Your SQL and YAML syntax is unchanged. What differs is enforcement: dbt v2 valid Check the [dbt Fusion documentation](https://docs.getdbt.com/docs/fusion/about-fusion) for engine-specific behavior and any features still landing. - The Lightdash CLI works with dbt v2: `lightdash deploy` and `lightdash preview` compile your project with the dbt you have installed, including dbt v2 and dbt OSS v2. When Lightdash compiles your project itself, on a [Git connection refresh](/integrations/dbt/projects#git-connection-methods), it uses dbt Core 1.x at the dbt version set in your [project connection settings](/integrations/connect-project#2-import-a-dbt-project). Keep your project compatible with dbt Core 1.10 or later so both paths compile it. + Git connection refreshes compile with dbt Core 1.x, while the CLI uses the dbt v2 you have installed. Keep your project compatible with dbt Core 1.10 or later so both compile it. From b213d6076ccdc2bb57e524ae7ce21838d775a7ee Mon Sep 17 00:00:00 2001 From: Jake Peterson <5532776+jpetey75@users.noreply.github.com> Date: Thu, 19 Nov 2026 14:40:33 -0600 Subject: [PATCH 3/4] Clear validator warnings on connect-project - Name warehouses and connection types instead of linking every section - Plain read-only recommendation Co-Authored-By: Claude Opus 5.5 --- integrations/connect-project.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/integrations/connect-project.mdx b/integrations/connect-project.mdx index f1b2682b0..f459b1ae3 100644 --- a/integrations/connect-project.mdx +++ b/integrations/connect-project.mdx @@ -33,9 +33,9 @@ Changing the warehouse connection doesn't change the tables in Explore. They sti ## 1. Connect to a warehouse -We currently support [BigQuery](#bigquery), [Postgres](#postgres), [Supabase](#supabase), [Redshift](#redshift), [Snowflake](#snowflake), [Databricks](#databricks), [Trino](#trino), [ClickHouse](#clickhouse), [DuckDB](#duckdb), and [Athena](#athena). If your warehouse isn't listed, you may still be able to connect to it through [Trino](#trino). +Lightdash supports BigQuery, Postgres, Supabase, Redshift, Snowflake, Databricks, Trino, ClickHouse, DuckDB and Athena, each with its own section below. If your warehouse isn't listed, you may still be able to connect to it through [Trino](#trino). -We always recommend giving read-only permissions to Lightdash, that way you ensure than no data can be manipulated. See each section below for warehouse specific details. +Give Lightdash read-only permissions so it can't change your data. A Postgres, Athena or Snowflake project can also query more than one warehouse. See [multiple warehouse connections](/workspace-admin/multiple-warehouse-connections). @@ -1506,7 +1506,7 @@ Then scroll down to the dbt project section: The **dbt version** field sets the dbt Core 1.x version Lightdash uses when it compiles your project. Lightdash supports dbt Core 1.4 to 1.12. The default, **latest**, uses the newest version Lightdash supports, currently 1.12. If a refresh fails with a dbt compile error and the project is pinned to an older version, choose a newer version, or **latest**, and refresh again. `lightdash deploy` and `lightdash preview` compile with the dbt you have installed, so for those, upgrade dbt locally. The list has no dbt v2 option: for a dbt v2 project, keep **latest** and keep the project compatible with dbt Core 1.10 or later, as described in [Moving to dbt v2](/integrations/dbt/upgrading#moving-to-dbt-v2-fusion). -Pick your connection type and follow the guide below: [GitHub](#github), [GitLab](#gitlab), [Azure DevOps](#azure-devops), [Bitbucket](#bitbucket), [dbt Cloud](#dbt-cloud), or the [CLI](#cli). +Pick your connection type (GitHub, GitLab, Azure DevOps, Bitbucket, dbt Cloud or the CLI) and follow its section below. **dbt Cloud managed repositories** From 49fd2ddaa90427a30de8bdc3b1a4f3f720bc6a54 Mon Sep 17 00:00:00 2001 From: Jake Peterson <5532776+jpetey75@users.noreply.github.com> Date: Thu, 19 Nov 2026 14:55:24 -0600 Subject: [PATCH 4/4] Keep the section links on Connect a project, per review Co-Authored-By: Claude Opus 5.5 --- integrations/connect-project.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/integrations/connect-project.mdx b/integrations/connect-project.mdx index f459b1ae3..21053b33f 100644 --- a/integrations/connect-project.mdx +++ b/integrations/connect-project.mdx @@ -33,7 +33,7 @@ Changing the warehouse connection doesn't change the tables in Explore. They sti ## 1. Connect to a warehouse -Lightdash supports BigQuery, Postgres, Supabase, Redshift, Snowflake, Databricks, Trino, ClickHouse, DuckDB and Athena, each with its own section below. If your warehouse isn't listed, you may still be able to connect to it through [Trino](#trino). +Lightdash supports [BigQuery](#bigquery), [Postgres](#postgres), [Supabase](#supabase), [Redshift](#redshift), [Snowflake](#snowflake), [Databricks](#databricks), [Trino](#trino), [ClickHouse](#clickhouse), [DuckDB](#duckdb) and [Athena](#athena). If your warehouse isn't listed, you may still be able to connect to it through [Trino](#trino). Give Lightdash read-only permissions so it can't change your data. @@ -1506,7 +1506,7 @@ Then scroll down to the dbt project section: The **dbt version** field sets the dbt Core 1.x version Lightdash uses when it compiles your project. Lightdash supports dbt Core 1.4 to 1.12. The default, **latest**, uses the newest version Lightdash supports, currently 1.12. If a refresh fails with a dbt compile error and the project is pinned to an older version, choose a newer version, or **latest**, and refresh again. `lightdash deploy` and `lightdash preview` compile with the dbt you have installed, so for those, upgrade dbt locally. The list has no dbt v2 option: for a dbt v2 project, keep **latest** and keep the project compatible with dbt Core 1.10 or later, as described in [Moving to dbt v2](/integrations/dbt/upgrading#moving-to-dbt-v2-fusion). -Pick your connection type (GitHub, GitLab, Azure DevOps, Bitbucket, dbt Cloud or the CLI) and follow its section below. +Pick your connection type and follow its section below: [GitHub](#github), [GitLab](#gitlab), [Azure DevOps](#azure-devops), [Bitbucket](#bitbucket), [dbt Cloud](#dbt-cloud), or the [CLI](#cli). **dbt Cloud managed repositories**