Skip to main content
Multiple warehouse connections are behind the multi-connection-projects feature flag, and the flow and wording on this page may change between releases. Contact Lightdash support to enable it for your organization. Self-hosted instances need an Enterprise license and multi-connection-projects in LIGHTDASH_ENABLE_FEATURE_FLAGS.
Use multiple connections when one project needs data from several databases of the same warehouse type, such as a production database and a read replica. On Snowflake, you can also use them to run different workloads on different warehouses, such as a small warehouse for dashboards and a large warehouse for heavy SQL runner work. If you only need more dbt projects on the same warehouse, use multiple dbt sources instead. When you switch, the current connection becomes the primary connection and everything that already exists stays on it. Each explore, SQL chart and virtual view runs on one connection.

​
Requirements and limits

  • You need permission to manage the project.
  • Only Postgres, Athena and Snowflake projects can switch, and every extra connection uses the primary’s warehouse type. You can’t change that type while extra connections exist. To mix warehouse types, see Mix warehouse types.
  • Preview projects can’t switch, and neither can a project whose warehouse uses organization credentials.
  • The switch is one way. You can remove extra connections, but the app can’t switch the project back.
  • One query can’t combine tables from two connections.
  • When the feature flag is off, no project can switch or add a connection. Projects that already switched keep working.

​
Enable multiple connections

In Project settings → Connection settings, click Enable multiple connections on the Connections card. If the button is disabled, its tooltip says why.
The Connections card on a single-connection project, with the Enable multiple connections button highlighted
Name the current connection, add the first extra connection, and click Review the switch. Lightdash tests the new connection before it shows the review.
The review step of the Enable multiple connections dialog, listing the added connection, the content that stays on the current connection and the no-way-back warning

​
Manage connections

The Connections card listing Primary warehouse with an Original badge, Reporting replica, and the Add connection button
Edit applies to extra connections. Edit the primary with the warehouse form on the same page. By default, the SQL runner sidebar lists only the database set on each connection. To list more on a Postgres or Athena connection, open the connection’s ⋯ menu and choose SQL runner databases:
  • Turn on List all databases to list every database the connection can read, up to 100.
  • Or leave it off and add names under Additional databases.
The setting is per connection. On Athena, List all databases calls Athena’s ListDatabases for the connection’s data catalog, so the connection’s AWS credentials need permission to list databases there. Without it, listing fails with an error that starts with Failed to list databases in catalog.

​
Snowflake connections

Each Snowflake connection has its own account, user, role, database and warehouse. To run different workloads on different Snowflake warehouses, add one connection for each warehouse. Then pick a connection in the SQL runner, or run a dbt source on it. A model’s snowflake_warehouse config and Always use this warehouse work on every connection the same way they work on a single-connection project.

​
Shared credentials or None

Two settings decide whose Snowflake login runs a query:
  • Require users to provide their own credentials on the primary connection. Every extra connection follows it.
  • Authentication Type on the connection. None means the connection stores no Snowflake login at all.
Which to choose:
  • Shared credentials, personal credentials not required: everyone can see the same data through one service user.
  • Personal credentials required: Snowflake roles and access policies must apply to each person.
  • None: the same as personal credentials required, and you don’t want a shared Snowflake login stored for this connection.
With User Account (Sign in with Snowflake) as shared credentials, the connection saves the Snowflake sign-in of the person who adds or edits it. To use None on an extra connection:
  • On the primary connection, turn on Require users to provide their own credentials and save. If this setting is off, None isn’t in the Authentication Type list.
  • Each person adds their own Snowflake credentials for the connection in the credentials switcher in the navigation bar. They can use Password, Key Pair (private key file) or User Account (Sign in with Snowflake). The sign-in option needs Snowflake OAuth on the instance. Self-hosted instances set it up with the Snowflake environment variables.
External Browser authentication isn’t allowed on an extra Snowflake connection. This applies when you enable multiple connections, add a connection, or edit one.

​
Mix warehouse types

Mixing warehouse types needs a second feature flag, mixed-warehouse-connections, on top of multi-connection-projects. Contact Lightdash support to enable it. Self-hosted instances add mixed-warehouse-connections to LIGHTDASH_ENABLE_FEATURE_FLAGS.
With mixed warehouse types, one project can hold connections to different warehouses, for example a Snowflake primary with a Trino or BigQuery connection next to it. Charts from each warehouse can then sit on the same dashboard. Each explore still runs on one connection, and Lightdash writes its SQL in that connection’s dialect. This applies to metrics, filters, custom dimensions, table calculations, date zoom, the SQL runner and the AI features.

​
Set it up

  1. Switch the project to multiple connections, as described in Enable multiple connections. Any warehouse type can be the primary.
  2. Click Add connection, then pick the warehouse in the Type list.
  3. Fill in the connection details. Lightdash tests the connection before it saves it.
  4. Run a dbt source on the new connection. See Run a dbt source on another connection.
The Add a connection dialog with the Type list open, showing several warehouse types
The explorer shows the connection name and its warehouse type above the results. The custom SQL dimension and SQL table calculation editors show which SQL dialect to write.
A dashboard with a Postgres tile and a DuckLake tile of Jaffle shop orders, each with its connection badge

​
Requirements

  • The multi-connection-projects and mixed-warehouse-connections feature flags, and on self-hosted instances an Enterprise license.
  • Supported warehouse types: BigQuery, ClickHouse, Databricks, DuckDB (MotherDuck and DuckLake), Postgres, Redshift, Snowflake, Trino and Athena.
  • The connection’s warehouse type can’t change after you add it. To use another type, add a new connection and move the dbt source to it.

​
Limits

  • One query, one connection. A join between models on different connections is skipped, and the explore shows a warning that names both connections. To combine results from two warehouses, use merge queries.
  • dbt refs stay on one connection. With cross-project refs between sources, a dbt source can only ref models from sources on the same connection.
  • Shared credentials for compiling. An extra connection compiles dbt with its shared credentials. BigQuery SSO and Redshift browser IAM sign-in can’t be used on an extra connection.
  • Personal credentials per connection. An extra connection of another warehouse type doesn’t follow the primary’s Require users to provide their own credentials setting. Turn it on in that connection’s advanced settings. A Snowflake connection with None authentication needs it on.
  • SQL runner databases is available for Postgres and Athena connections only.
  • AI agents know about every connection and its dialect, but the agent’s raw SQL tool runs on the primary connection.
  • Week start in dashboard filters. Dashboard-wide filters use the primary connection’s week start in the filter bar. Each tile’s query uses its own connection’s week start.
  • When the mixed-warehouse-connections flag is off, only same-type connections can be added. Connections that already exist keep working.

​
Errors you may see

​
Run a dbt source on another connection

The primary dbt source always runs on the primary connection. Each additional dbt source can run on any connection, and its explores move on the next compile.
The dbt sources panel with the connection select of an additional source highlighted and set to Reporting replica, and a note offering Compile now
Two connections can’t produce explores with the same name. If they do, the compile fails and names both connections.

​
Query a connection in the SQL runner

The SQL runner with the Connection picker highlighted and set to Reporting replica, and both connections in the table tree
Queries, saved charts and virtual views use the active connection. The SQL runner remembers your last connection for each project in this browser. Share links keep their connection, and Open in SQL Runner from an explore opens on that explore’s connection. To move a SQL chart, open it, pick the other connection and save. Run it first to check that the SQL works there. A virtual view can’t move, so create a new one on the other connection.

​
Explores, charts and dashboards

The explore list with the connection filter open and a connection badge next to an explore
A dashboard can mix connections. Each tile, with its underlying data, downloads and scheduled deliveries, runs on the tile’s own connection. Embedded dashboards run the same way without the connection badges.
A dashboard with a tile on Reporting replica next to a tile on Primary warehouse

​
Personal warehouse credentials

Extra connections of the primary’s warehouse type follow the primary’s Require users to provide their own credentials setting. With mixed warehouse types, an extra connection of another type has its own setting. When it is on, people need personal credentials for each connection they query, and the credentials switcher in the navigation bar has one section per connection.
The SQL runner on Reporting replica without personal credentials, with a message that names the connection and points to the credentials switcher

​
Deploy from the CLI

lightdash deploy without a source deploys to the primary connection. To deploy explores to an extra connection, name the dbt source that runs there:
The other sources keep their explores. lightdash preview and lightdash start-preview take the same flag, and lightdash config set-source stores a default. The deploy stops if your dbt target’s database doesn’t match the connection. See the CLI reference. Preview projects copy every connection, and their explores and SQL charts use the copies.

​
Content as code and promotion

SQL charts and virtual views on an extra connection download with the connection’s name, for example connection: Reporting replica. Content on the primary has no connection: field. An upload can’t move content to another connection. A file that names another connection, or drops the field, fails:
Promotion matches SQL chart connections by name and stops if the upstream project has no connection with that name.

​
Remove a connection

You can remove an extra connection only when no explores, dbt sources, SQL charts or running queries use it. The primary can’t be removed. Move that content first, or contact Lightdash support if you can’t. When the last extra connection goes, the project works like a single-connection project again.
The Remove connection dialog refusing to remove Reporting replica because a SQL chart uses it
If an extra connection fails during a compile, its explores stay as they were and a warning names the connection. If the primary fails, the compile fails as usual.
A Connections failed to compile warning for Reporting replica, saying its previous explores are kept