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 up at dbdeux.com)
• 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. Navigate to Connections

Click your avatar in the top-right corner, then select Settings → Connections.

2. Add a New Connection

Click + Add Connection and select your warehouse type from the list.

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
Password	Password for the account	••••••••
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:

• USAGE on the warehouse
• USAGE on the database
• CREATE TABLE, CREATE VIEW on target schemas
• SELECT on 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 Editor on target datasets
• BigQuery Data Viewer on source datasets
• BigQuery Job User on 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:

• CREATE permission on the target schema
• SELECT on source schemas
• USAGE on 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 Key-Pair Authentication

As an alternative to password authentication, Snowflake connections support RSA key-pair authentication:

1. Select Key Pair as the authentication method
2. Upload your RSA private key (PEM format)
3. Enter the passphrase if the key is encrypted

Key-pair auth is recommended for service accounts and automated environments where passwords are not ideal. Password and key-pair are treated as an either/or choice, so supplying one means you do not also need the other, and validation will not flag the unused method as missing.

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.

---

4. Test the Connection

Click Test Connection. dbdeux will:

1. Attempt to establish a connection using your credentials
2. Run a lightweight query to verify permissions
3. Confirm access to the specified database/schema

If successful, you will see a green confirmation. If not, see troubleshooting below.

5. Assign to a Project

Navigate to your project settings and select the connection under Environment → Connection. Each project uses one connection at a time, but you can have different connections for different environments (dev, staging, production).

Editing Connections

You can update existing connections at any time without recreating them:

1. Go to Settings → Connections
2. Click the connection you want to modify
3. Update any field (credentials, host, database, schema, etc.)
4. Click Test Connection to verify the updated settings
5. Save your changes

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.

Databases

4 connections

❄Snowflake Prod

◈BigQuery Staging

◆Redshift Dev

⬡Fabric Warehouse

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 connection
• team:data-platform - Which team uses it
• domain:finance - Business domain
• contact: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

1. Open a connection's settings (Add or Edit)
2. In the Tags field, type a tag name and press Enter
3. Tags are de-duplicated (case-insensitive) and limited to 15 per connection
4. 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).

🔗

Copy Template

Export your connection as a shareable token - secrets are automatically stripped

→

📤

Share Token

Send the token to a teammate via chat, email, or docs

→

📋

Paste & Import

Teammate pastes the token to pre-fill host, port, database, and role

→

🔑

Add Credentials

Only the required secrets need to be entered to complete the connection

Connection Template - What Gets Shared

hostacme.snowflakecomputing.comIncluded

port443Included

databaseANALYTICS_DBIncluded

warehouseCOMPUTE_WHIncluded

roleTRANSFORMERIncluded

schemaPUBLICIncluded

password********Stripped

private_key********Stripped

Generated Token

DBDEUX-CONN-1:eyJhZGFwdGVyIjoic25vd2ZsYWtlIiwiaG9zdCI6ImFjbWUuc25vd2ZsYWtl...

How it works

1. Copy: Open a connection's settings and click Copy as Template. A token string beginning with DBDEUX-CONN-1: is copied to your clipboard
2. Share: Send the token to your teammate via Slack, email, or internal docs
3. Import: Your teammate clicks New Connection and pastes the token. All non-secret fields are pre-filled automatically
4. 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)