Connecting Your Warehouse
This guide walks you through adding a data warehouse connection to dbdeux. Connections are how dbdeux executes queries against your data platform.
Prerequisites
- A dbdeux account (sign in at dbdeux.datalakehouse.io)
- Credentials for your data warehouse with appropriate permissions
- Network access configured (see IP Allowlist if your warehouse restricts access by IP)
Step-by-Step Setup
1. Open the Databases Page
Click Databases in the left navigation. This page lists every warehouse connection you can see, with the workspace each one belongs to.
2. Add a New Connection
Click New Connection and select your warehouse type in the drawer that opens.
3. Enter Credentials
Fill in the connection form. Required fields vary by warehouse:
Snowflake
| Field | Description | Example |
|---|---|---|
| Account | Your Snowflake account identifier | xy12345.us-east-1 |
| Username | Service account or user name | DBT_USER |
| Authentication | Key Pair (RSA), Programmatic Access Token (PAT), External OAuth, or Snowflake OAuth on developer sandboxes. See Snowflake Authentication | Key Pair (RSA) |
| Key, token, or OAuth details | The credential for the method you picked | •••••••• |
| Role | Snowflake role with appropriate permissions | TRANSFORMER |
| Warehouse | Compute warehouse for running queries | ANALYTICS_WH |
| Database | Target database | ANALYTICS |
| Schema | Default schema (can be overridden per project) | DBT_PROD |
The Account field expects just the identifier (for example xy12345.us-east-1). If you paste the full host, the trailing .snowflakecomputing.com suffix is stripped automatically so the connection uses the correct value.
Recommended setup: Create a dedicated service account for dbdeux with a role that has:
USAGEon the warehouseUSAGEon the databaseCREATE TABLE,CREATE VIEWon target schemasSELECTon source schemas
Google BigQuery
| Field | Description | Example |
|---|---|---|
| Project | GCP project ID | my-analytics-project |
| Dataset | Default dataset | analytics |
| Location | Dataset region | US, EU |
| Service Account Key | JSON key file for authentication | Upload .json file |
Recommended setup: Create a dedicated service account with these roles:
BigQuery Data Editoron target datasetsBigQuery Data Vieweron source datasetsBigQuery Job Useron the project
Amazon Redshift
| Field | Description | Example |
|---|---|---|
| Host | Cluster endpoint | my-cluster.abc123.us-east-1.redshift.amazonaws.com |
| Port | Connection port | 5439 |
| Database | Target database | analytics |
| Username | Database user | dbt_user |
| Password | Database password | •••••••• |
| Schema | Default schema | public |
Recommended setup: Create a dedicated user with:
CREATEpermission on the target schemaSELECTon source schemasUSAGEon the target schema
Amazon Athena
| Field | Description | Example |
|---|---|---|
| Region | AWS region | us-east-1 |
| S3 Staging Directory | Where Athena writes query results | s3://my-bucket/athena-results/ |
| Database | Glue catalog database | analytics |
| Workgroup | Athena workgroup | primary |
| Access Key | AWS access key ID | AKIA... |
| Secret Key | AWS secret access key | •••••••• |
Databricks
| Field | Description | Example |
|---|---|---|
| Host | Databricks workspace URL | adb-1234567890.12.azuredatabricks.net |
| HTTP Path | SQL Warehouse HTTP path | /sql/1.0/warehouses/abc123 |
| Access Token | Personal access token or service principal token | dapi... |
| Catalog | Unity Catalog name | main |
| Schema | Default schema | analytics |
Recommended setup: Create a service principal with appropriate grants on the target catalog and schemas.
PostgreSQL
| Field | Description | Example |
|---|---|---|
| Host | Database server hostname | my-db.example.com |
| Port | Connection port | 5432 |
| Database | Target database | analytics |
| Username | Database user | dbt_user |
| Password | Database password | •••••••• |
| Schema | Default schema | public |
Recommended setup: Create a dedicated user with CREATE and SELECT permissions on the relevant schemas.
MotherDuck
| Field | Description | Example |
|---|---|---|
| Database | MotherDuck database name (defaults to my_db if omitted) | analytics |
| Schema | Default schema | main |
| Token | MotherDuck service token for authentication | •••••••• |
MotherDuck is cloud-hosted DuckDB. dbdeux connects via the dbt-duckdb adapter using the md: scheme, so your dbt project runs against your MotherDuck databases without any local setup.
Recommended setup: Generate a service token from your MotherDuck dashboard. Use a dedicated token per environment for easy rotation.
Microsoft Fabric
| Field | Description | Example |
|---|---|---|
| Host | Fabric SQL endpoint | abc123.datawarehouse.fabric.microsoft.com |
| Database | Fabric Warehouse database name | analytics_wh |
| Schema | Default schema | dbo |
| Tenant ID | Azure AD (Entra ID) tenant | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| Client ID | Service principal application ID | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| Client Secret | Service principal secret | •••••••• |
Recommended setup: Create an Entra ID service principal with access to your Fabric Warehouse. Fabric connections use the T-SQL protocol via the dbt-fabric adapter.
Azure Synapse
| Field | Description | Example |
|---|---|---|
| Host | Synapse SQL endpoint | myworkspace.sql.azuresynapse.net |
| Database | SQL pool database | analytics |
| Schema | Default schema | dbo |
| Username | SQL login (password auth) | dbt_user |
| Password | SQL password | •••••••• |
Azure Synapse also supports Entra ID service principal authentication (Tenant ID, Client ID, Client Secret) as an alternative to SQL login.
Recommended setup: Create a dedicated SQL login or Entra ID service principal with appropriate permissions on target schemas.
Microsoft Fabric Lakehouse
| Field | Description | Example |
|---|---|---|
| Workspace ID | Fabric workspace GUID | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| Lakehouse ID | Lakehouse GUID | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| Lakehouse | Lakehouse name | analytics_lakehouse |
| Schema | Default schema | dbo |
| Tenant ID | Azure AD (Entra ID) tenant | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| Client ID | Service principal application ID | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
| Client Secret | Service principal secret | •••••••• |
Fabric Lakehouse runs dbt on Spark via OneLake using the dbt-fabricspark adapter. Requires dbt 1.10 or later.
Recommended setup: Create an Entra ID service principal with Contributor access to the Fabric Workspace containing your Lakehouse.
Snowflake Authentication: Choosing a Method
Snowflake has retired single-factor password sign-in, and dbdeux follows that lead: a new Snowflake connection is created with a key, a token, or OAuth, never a password. Four methods are offered, and the right one depends on a single question: who is the connection acting as?
| Method | Acts as | Runs unattended (jobs, pull request builds, Semantic Layer, AI assistants) | Revoked from | Choose it when |
|---|---|---|---|---|
| Key Pair (RSA) | A Snowflake service user | Yes | Snowflake | The simplest default for shared, staging, and production connections |
| Programmatic Access Token | A Snowflake user, often MFA-enforced | Yes | Snowflake | You want to connect quickly without key management, and keep the role and expiry you set on the token |
| External OAuth | A service identity in Entra ID or Okta | Yes | Your identity provider | Security policy says warehouse access must federate through your identity provider, or access must be revocable centrally without touching Snowflake or dbdeux |
| Snowflake OAuth | Each developer, with their own Snowflake user | No, sandboxes only | Snowflake, or the developer | Every developer should work as themselves on a developer sandbox rather than sharing one login |
The first three sign in without a person present, which is what scheduled jobs and pull request builds need. Snowflake OAuth is the interactive counterpart for sandboxes, where the whole point is that runs and previews happen as the person at the keyboard. Every method is an either/or choice: fill in the one you are using and validation will not ask for the others.
Snowflake Key-Pair Authentication
- Select Key Pair (RSA) as the authentication method
- Upload your RSA private key (PEM format)
- Enter the passphrase if the key is encrypted
Key-pair auth is the recommended default for service users and automated environments.
Templated profiles: If your profiles.yml uses env_var() to reference the private key (e.g., private_key_path: "{{ env_var('SNOWFLAKE_PRIVATE_KEY_PATH') }}"), dbdeux automatically projects the uploaded key into the correct environment variable during runs. You do not need to manually set the env var. The Variables tab on the Environment page documents which key-pair env vars are automatically provided.
Snowflake Programmatic Access Tokens
Snowflake connections also support Programmatic Access Token (PAT) authentication, which is often the quickest way to connect an account that enforces multi-factor authentication.
- Select Programmatic Access Token (PAT) as the authentication method
- In Snowsight, open your user profile, then Settings > Authentication > Programmatic access tokens, and generate a token
- Paste the token into the connection
Why teams reach for this:
- It works with MFA. A password on an MFA-enforced user cannot be used for an automated connection. A programmatic access token can, without anyone disabling a security control to get dbt running
- It stays scoped. The token honours the role restriction and expiry you set when you created it, so a connection cannot quietly outlive or out-reach what you granted it
- No key management. Nothing to generate, register, or rotate on the Snowflake user, which suits a trial or a first connection where key-pair setup is more ceremony than it is worth
For long-lived production service users, key-pair authentication remains the sturdiest option.
Snowflake External OAuth (Entra ID or Okta)
Many security teams want warehouse access to be an identity their identity provider controls, not a key that lives in a tool. External OAuth (Entra ID / Okta service identity) does exactly that: dbdeux signs in to Snowflake as an application registered in your identity provider, and Snowflake trusts that identity provider.
- Select External OAuth as the authentication method
- Follow the built-in setup guide in the connection drawer. It walks through registering the application (Entra ID) or creating the application and authorization server (Okta), creating the matching External OAuth integration and service user in Snowflake, and which value goes in which field
- Fill in the token endpoint, client ID, client secret, and the scope or audience your setup uses, then Test connection
What you get from it:
- Everything unattended works. Scheduled jobs, pull request builds, the Semantic Layer, and AI assistants all use the connection exactly as they would a key pair. Long runs fetch a fresh sign-in whenever they need one, so token lifetime is never something you tune
- One switch turns it off. Disable the application or rotate its secret in Entra ID or Okta and dbdeux loses access within one token lifetime, with nothing to change in Snowflake or in dbdeux. That is the difference from a key: a key held in a tool is an identity your identity provider cannot revoke
- Key Pair is still fine. Choose External OAuth because your policy asks for it, not because key pair is lacking. Most teams run production on key pair and adopt External OAuth where federation is a requirement
Snowflake OAuth: Each Developer Signs In
A shared service login on a development connection means every developer's queries look identical in Snowflake's own history and every developer holds the same power. On a developer sandbox, dbdeux offers Snowflake OAuth (each developer signs in) instead:
- On an environment with Developer sandbox DB turned on, select Snowflake OAuth as the authentication method and enter the client ID and secret from the Snowflake security integration (the drawer includes the guide for creating it)
- Each developer opens the connection and clicks Connect your Snowflake account, signing in with their own Snowflake user
- From then on their dbt runs, previews, and warehouse browsing on that connection happen as them
The connection panel shows who is connected, the role in use, and when the sign-in expires. A developer stays connected for up to 90 days, gets a heads-up when the sign-in is about to expire, and simply clicks Reauthorize when it does. Disconnect is one click away for anyone who wants to sign out of the warehouse without touching the connection itself.
Two guardrails are built in. Snowflake refuses OAuth for its most privileged roles (ACCOUNTADMIN, SECURITYADMIN, ORGADMIN) by default, so set the connection's Role to a sandbox role developers can actually assume. And because scheduled jobs and pull request builds run with nobody signed in, they cannot use a per-developer connection: the method is only offered on sandboxes, and Slimmer CI tells you plainly if the connection you picked needs a developer present.
If You Still Have a Password Connection
Existing Snowflake connections that were created with a password keep working for now, but they are marked so nobody is surprised later:
- The connection carries a Deprecated authentication method banner with a Switch by date, counting down ("112 days left", "due tomorrow") and turning to "overdue" once the date passes. Your Snowflake authentication policy may refuse the saved password before then, and the banner explains why a connection that tested fine last quarter now fails
- A Deprecated auth pill on the Databases list lets you find every such connection at a glance without opening each one
- Switch to Key Pair (RSA) or Switch to Programmatic Access Token on the banner changes only the credential. Account, user, warehouse, database, schema, and role are all kept, so migrating a connection is a paste and a save, not a rebuild
- Switching a connection back onto a password is not offered
4. Test the Connection
Click Test Connection. dbdeux will:
- Attempt to establish a connection using your credentials
- Run a lightweight query to verify permissions
- Confirm access to the specified database/schema
If successful, you will see a green confirmation. If not, see troubleshooting below.
5. Assign to an Environment
Open Environments in the left navigation and pick the connection each environment should use. A project can point different environments at different connections, so development, staging, and production each run against the right warehouse.
Editing Connections
You can update existing connections at any time without recreating them:
- Open Databases in the left navigation
- Click the connection you want to modify
- Update any field (credentials, host, database, schema, etc.)
- Click Test Connection to verify the updated settings
- Save your changes
When you test while editing, the test uses the values currently on the form, not the last saved ones. Change an account identifier or a role and the test tells you whether that change works before you commit to it, instead of confirming the settings you were trying to replace. Secret fields you leave blank keep using the stored secret, so you can retest a warehouse or schema change without retyping a password, and nothing is saved by the test itself.
Active runs are not affected. Updated credentials take effect on the next run.
Masked Connection Identity
Identifying values such as the account identifier and host are masked by default whenever a connection is displayed or edited. Click the eye toggle next to a field to reveal it when you genuinely need to read or copy it. This keeps sensitive account and host details from being exposed on shared screens, in screen shares, or in screenshots, without getting in the way of day-to-day work.
Connection Tags
Tags are free-form labels you attach to a connection for visibility, filtering, and safety. They help teams organize connections across environments, owners, and domains.
Environment Tags
Special environment tags are automatically recognized and color-coded:
| Tag | Recognized spellings | Color |
|---|---|---|
| Production | prod, production, prd, live | Red |
| Staging | staging, stage, stg, preprod, pre-prod, uat | Amber |
| Dev | dev, develop, development, sandbox, local, test | Green |
Namespaced Tags
Use the namespace:value format to add structured metadata:
owner:analytics-eng- Who owns this connectionteam:data-platform- Which team uses itdomain:finance- Business domaincontact:jane@company.com- Point of contact
Namespaced tags render with a labeled prefix and a per-namespace icon for quick identification.
Filtering and Grouping
- Click any tag chip in the Databases list to filter connections by that tag
- Use the Group by tag toggle to organize connections by tag instead of a flat list
- Tag chips appear on the connection picker in the editor and the status bar, so you always know which connection you are using
Production Run Guardrail
When a connection is tagged as production (prod, production, live, etc.), dbdeux shows a confirmation dialog before running write operations (run, build, seed, snapshot) against it. Read-only commands (compile, list, show) are not gated. This prevents accidental materializations in production warehouses.
Managing Tags
- Open a connection's settings (Add or Edit)
- In the Tags field, type a tag name and press Enter
- Tags are de-duplicated (case-insensitive) and limited to 15 per connection
- Click the X on any tag chip to remove it
Shareable Connection Templates
Connection Templates let you share your connection configuration with teammates without exposing secrets. When you copy a connection as a template, dbdeux generates a portable token that includes all non-sensitive fields (host, port, database, warehouse, role, schema) and automatically strips credentials (password, private key, tokens, access keys).
How it works
- Copy: Open a connection's settings and click Copy as Template. A token string beginning with
DBDEUX-CONN-1:is copied to your clipboard - Share: Send the token to your teammate via Slack, email, or internal docs
- Import: Your teammate clicks New Connection and pastes the token. All non-secret fields are pre-filled automatically
- Complete: Only the required credentials (password, key, or token) need to be entered to finish the connection
What gets included and excluded
| Included (shared) | Excluded (stripped) |
|---|---|
| Host, port, database | Password |
| Warehouse, role, schema | Private key and passphrase |
| Adapter type, threads | OAuth tokens and client secrets |
| Account identifier | AWS access keys and session tokens |
| Connection name | Keyfile JSON |
This makes onboarding new team members faster and reduces the risk of misconfigured connections since the infrastructure details are pre-filled.
Security
All credentials are:
- Encrypted at rest with AES-256
- Encrypted in transit with TLS 1.3
- Accessible only to organization Admins
- Never logged or displayed in plain text after saving
→ Learn more about Security & Compliance
Troubleshooting
| Problem | Solution |
|---|---|
| Connection timeout | Ensure dbdeux IPs are allowlisted. See IP Allowlist |
| Permission denied | Verify the user/role has appropriate access to target schemas |
| Invalid credentials | Double-check the account identifier format and password |
| Snowflake "JWT token is invalid" | This is a key-pair setup issue. Confirm the username matches the key's owner, the public key is registered on that Snowflake user, and the account identifier is correct. dbdeux surfaces this guidance directly on a failed run so you know it is a key or account mismatch, not a transient error |
| SSL/TLS error | Ensure your warehouse supports TLS connections (required) |
| Database not found | Verify the database name matches exactly (case-sensitive for some warehouses) |