Warehouses¶

Altimate Code connects to 13 warehouse types. Configure them in .altimate-code/connections.json (project-local) or ~/.altimate-code/connections.json (global).

Configuration¶

Each warehouse has a key (the connection name) and a config object:

{
  "my-connection-name": {
    "type": "<warehouse-type>",
    ...
  }
}

Tip

Use {env:...} substitution for passwords and tokens so you never commit secrets to version control.

Where saved passwords go

When the agent adds a connection for you, passwords, keys and tokens are kept in your OS credential store (macOS Keychain, Windows Credential Manager, or libsecret on Linux), never in connections.json. If no credential store is available, the credential is not saved: the connection works for that session only, and Altimate Code says so. In that case set an ALTIMATE_CODE_CONN_<NAME> environment variable to the connection's full config as JSON (not just the password); for a name containing -, set it with env, since a shell assignment cannot use that character. Removing a saved connection removes its credentials from the store, unless this project's connections file or an environment variable still defines a connection by that name. Saving a connection again under the same name drops the credentials it no longer uses once the new config is written. Credentials are stored by connection name, so a project file that defines a connection of the same name without its own password was using the saved connection's, and loses it when that one is removed. If the store refuses a removal, Altimate Code says which credentials remain.

Snowflake¶

{
  "prod-snowflake": {
    "type": "snowflake",
    "account": "xy12345.us-east-1",
    "user": "analytics_user",
    "password": "{env:SNOWFLAKE_PASSWORD}",
    "warehouse": "COMPUTE_WH",
    "database": "ANALYTICS",
    "role": "ANALYST_ROLE"
  }
}

Field	Required	Description
`account`	Yes	Snowflake account identifier (e.g. `xy12345.us-east-1`)
`user`	Yes	Username
`password`	Auth	Password (use one auth method)
`private_key_path`	Auth	Path to private key file (alternative to password)
`private_key_passphrase`	No	Passphrase for encrypted private key
`warehouse`	No	Warehouse name
`database`	No	Database name
`schema`	No	Schema name
`role`	No	User role
`client_session_keep_alive`	No	Keep the session alive while Altimate Code is running (default `true`). A connection Snowflake closes anyway is reopened automatically. `USE`, `ALTER SESSION` and `SET` settings are applied again to the reopened session. A single read-only query interrupted by the close is run again; a statement that changes data, or calls a sequence, is not, because it may already have run, and the error says so. Temporary tables and an open transaction cannot be restored: statements issued before the reopen report that instead of running. Each reopen is written to `opencode.log` under `warehouse-connect` as `reconnecting`, then `reconnected` (with `reason`, `duration_ms`, `settings_restored` and `session_state_lost`) or `reconnect failed` (a warning with the masked error). The lines name the account, and the connection when only one uses that account; they never contain SQL.

Key-pair authentication¶

{
  "prod-snowflake": {
    "type": "snowflake",
    "account": "xy12345.us-east-1",
    "user": "svc_altimate",
    "private_key_path": "~/.ssh/snowflake_rsa_key.p8",
    "private_key_passphrase": "{env:SNOWFLAKE_KEY_PASSPHRASE}",
    "warehouse": "COMPUTE_WH",
    "database": "ANALYTICS",
    "role": "TRANSFORM_ROLE"
  }
}

Browser single sign-on¶

Set "authenticator": "externalbrowser" (and no password) to sign in through your identity provider.

{
  "snowflake-sso": {
    "type": "snowflake",
    "account": "xy12345.us-east-1",
    "user": "jane.doe@example.com",
    "authenticator": "externalbrowser",
    "warehouse": "COMPUTE_WH"
  }
}

When a connection opens, Snowflake's sign-in page opens in your default browser, and Altimate Code shows Waiting for sign-in with a link to the same page in case no browser tab appeared. Snowflake waits up to two minutes for the sign-in. If it isn't completed in that time, the connection fails with a message saying so; complete the sign-in, then try again. If you'd rather not sign in through the browser, use key-pair authentication.

A connection that does not use the browser fails after two minutes without an answer from Snowflake, with a message pointing at network, VPN or proxy settings, instead of retrying silently.

BigQuery¶

{
  "bigquery-prod": {
    "type": "bigquery",
    "project": "my-gcp-project",
    "credentials_path": "/code/path/to/service-account.json",
    "location": "US"
  }
}

Field	Required	Description
`project`	Yes	Google Cloud project ID
`credentials_path`	No	Path to service account JSON file. Omit to use Application Default Credentials (ADC)
`location`	No	Default location (default: `US`)

Using Application Default Credentials¶

If you're already authenticated via gcloud, omit credentials_path:

{
  "bigquery-prod": {
    "type": "bigquery",
    "project": "my-gcp-project"
  }
}

Databricks¶

{
  "databricks-prod": {
    "type": "databricks",
    "server_hostname": "adb-1234567890.1.azuredatabricks.net",
    "http_path": "/code/sql/1.0/warehouses/abcdef1234567890",
    "access_token": "{env:DATABRICKS_TOKEN}",
    "catalog": "main",
    "schema": "default"
  }
}

Field	Required	Description
`server_hostname`	Yes	Databricks workspace hostname
`http_path`	Yes	HTTP path from compute resources
`access_token`	Yes	Personal Access Token (PAT)
`catalog`	No	Unity Catalog name
`schema`	No	Schema/database name

Trino¶

{
  "trino-prod": {
    "type": "trino",
    "host": "trino.example.com",
    "port": 8443,
    "protocol": "https",
    "catalog": "iceberg",
    "schema": "analytics",
    "user": "analyst",
    "password": "{env:TRINO_PASSWORD}"
  }
}

Field	Required	Description
`connection_string`	No	Full server URL (alternative to host/port, e.g. `https://trino.example.com:8443`)
`host`	No	Hostname (default: `localhost`)
`port`	No	Port (default: `8080`, or `8443` when `protocol` is `https`)
`protocol`	No	`http` or `https` (default: `http`)
`catalog`	Recommended	Default catalog for query execution and required for schema/table introspection
`schema`	No	Default schema
`user`	No	Trino user (default sent by the client if omitted)
`password`	Auth	Basic authentication password
`access_token`	Auth	Bearer/JWT token
`extra_headers`	No	Additional HTTP headers to send to Trino

Using a bearer token¶

{
  "trino-prod": {
    "type": "trino",
    "connection_string": "https://trino.example.com:8443",
    "catalog": "hive",
    "schema": "default",
    "access_token": "{env:TRINO_TOKEN}"
  }
}

PostgreSQL¶

{
  "my-postgres": {
    "type": "postgres",
    "host": "localhost",
    "port": 5432,
    "database": "analytics",
    "user": "analyst",
    "password": "{env:PG_PASSWORD}"
  }
}

Field	Required	Description
`connection_string`	No	Full connection string (alternative to individual fields)
`host`	No	Hostname (default: `localhost`)
`port`	No	Port (default: `5432`)
`database`	No	Database name (default: `postgres`)
`user`	No	Username
`password`	No	Password

Using a connection string¶

{
  "my-postgres": {
    "type": "postgres",
    "connection_string": "postgresql://analyst:secret@localhost:5432/analytics"
  }
}

Special characters in passwords

Passwords with special characters (@, #, :, /) are automatically percent-encoded. No manual escaping required.

Redshift¶

{
  "redshift-prod": {
    "type": "redshift",
    "host": "my-cluster.abc123.us-east-1.redshift.amazonaws.com",
    "port": 5439,
    "database": "analytics",
    "user": "admin",
    "password": "{env:REDSHIFT_PASSWORD}"
  }
}

Field	Required	Description
`connection_string`	No	Full connection string (alternative to individual fields)
`host`	No	Hostname
`port`	No	Port (default: `5439`)
`database`	No	Database name (default: `dev`)
`user`	No	Username
`password`	No	Password
`iam_role`	No	IAM role ARN (alternative to password)
`region`	No	AWS region (default: `us-east-1`)
`cluster_identifier`	No	Cluster identifier (required for IAM auth)

IAM authentication¶

{
  "redshift-prod": {
    "type": "redshift",
    "host": "my-cluster.abc123.us-east-1.redshift.amazonaws.com",
    "database": "analytics",
    "user": "admin",
    "iam_role": "arn:aws:iam::123456789012:role/RedshiftReadOnly",
    "cluster_identifier": "my-cluster",
    "region": "us-east-1"
  }
}

DuckDB¶

{
  "dev-duckdb": {
    "type": "duckdb",
    "path": "./dev.duckdb"
  }
}

Field	Required	Description
`path`	Yes	Database file path, or `":memory:"` for in-memory. Cannot be omitted — a missing `path` is rejected rather than silently falling back to `":memory:"`
`create`	No	Create the database file if it is missing (default: `false`)

The store must already exist

Connecting never creates the database. If the file is missing, the connection fails with an error naming the path it looked for — an empty database would otherwise answer every query with no rows and no error, which reads as a successful query against an empty warehouse. Set "create": true only when you intend this store to be created.

How a relative path is resolved

A relative path is resolved once, when the config is loaded, against the directory that declares it:

~/.altimate-code/connections.json → resolved against ~/.altimate-code
<project>/.altimate-code/connections.json → resolved against <project>
ALTIMATE_CODE_CONN_* environment variables → resolved against the project root

It is never resolved against the current working directory, so --dir cannot re-point an existing connection at a different file. Absolute paths are always safest.

Bare word:target values are treated as local files

A path shaped like word:target with no // (for example data:warehouse.duckdb) is treated as an ordinary local filename by default. The only exceptions are md:, motherduck:, and ducklake: — these specific bare prefixes are recognized remote storage schemes and are always forwarded as remote targets. To force any other value to be treated as remote, use its full scheme:// form (s3://..., md://...) instead of a bare prefix.

Concurrent access

DuckDB does not support concurrent write access to the same file. If another process holds a write lock, Altimate Code automatically retries the connection in read-only mode so you can still query the data. A clear error message is shown if read-only access also fails.

MySQL¶

{
  "mysql-prod": {
    "type": "mysql",
    "host": "localhost",
    "port": 3306,
    "database": "analytics",
    "user": "analyst",
    "password": "{env:MYSQL_PASSWORD}"
  }
}

Field	Required	Description
`host`	No	Hostname (default: `localhost`)
`port`	No	Port (default: `3306`)
`database`	No	Database name
`user`	No	Username
`password`	No	Password
`ssl_ca`	No	Path to CA certificate file
`ssl_cert`	No	Path to client certificate file
`ssl_key`	No	Path to client key file

MongoDB¶

{
  "my-mongodb": {
    "type": "mongodb",
    "host": "localhost",
    "port": 27017,
    "database": "analytics",
    "user": "analyst",
    "password": "{env:MONGO_PASSWORD}"
  }
}

Field	Required	Description
`connection_string`	No	Full connection string (alternative to individual fields)
`host`	No	Hostname (default: `127.0.0.1`)
`port`	No	Port (default: `27017`)
`database`	No	Database name
`user`	No	Username
`password`	No	Password
`auth_source`	No	Authentication database (default: `admin`)
`replica_set`	No	Replica set name
`tls`	No	Enable TLS (default: `false`)
`direct_connection`	No	Connect directly to a single host

Using a connection string¶

{
  "my-mongodb": {
    "type": "mongodb",
    "connection_string": "mongodb://analyst:secret@localhost:27017/analytics"
  }
}

Note

MongoDB uses MQL (MongoDB Query Language) instead of SQL. Queries are submitted as JSON objects via the execute method. Supported commands: find, aggregate, countDocuments, distinct, insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany, createIndex, listIndexes, createCollection, dropCollection, ping.

Blocked operators

For safety, aggregate pipelines block $out and $merge (write stages) and $function and $accumulator (arbitrary JavaScript execution). Use find, countDocuments, or safe aggregate stages for read-only analysis.

Server compatibility

The MongoDB driver (v6.x) supports MongoDB server versions 3.6 through 8.0, covering all releases from the last 3+ years.

ClickHouse¶

{
  "clickhouse-prod": {
    "type": "clickhouse",
    "host": "localhost",
    "port": 8123,
    "database": "analytics",
    "user": "default",
    "password": "{env:CLICKHOUSE_PASSWORD}"
  }
}

Field	Required	Description
`connection_string`	No	Full URL (alternative to individual fields, e.g. `http://user:pass@host:8123`)
`host`	No	Hostname (default: `localhost`)
`port`	No	HTTP port (default: `8123`)
`database`	No	Database name (default: `default`)
`user`	No	Username (default: `default`)
`password`	No	Password
`protocol`	No	`http` or `https` (default: `http`)
`request_timeout`	No	Request timeout in ms (default: `30000`)
`tls_ca_cert`	No	Path to CA certificate for TLS
`tls_cert`	No	Path to client certificate for mutual TLS
`tls_key`	No	Path to client key for mutual TLS
`clickhouse_settings`	No	Object of ClickHouse server settings

ClickHouse Cloud¶

{
  "clickhouse-cloud": {
    "type": "clickhouse",
    "host": "abc123.us-east-1.aws.clickhouse.cloud",
    "port": 8443,
    "protocol": "https",
    "user": "default",
    "password": "{env:CLICKHOUSE_CLOUD_PASSWORD}",
    "database": "default"
  }
}

Using a connection string¶

{
  "clickhouse-prod": {
    "type": "clickhouse",
    "connection_string": "https://default:secret@my-ch.cloud:8443"
  }
}

Server compatibility

The ClickHouse driver supports ClickHouse server versions 23.3 and later, covering all non-EOL releases. This includes LTS releases 23.8, 24.3, 24.8, and all stable releases through the current version.

Oracle¶

{
  "oracle-prod": {
    "type": "oracle",
    "host": "localhost",
    "port": 1521,
    "service_name": "ORCL",
    "user": "analyst",
    "password": "{env:ORACLE_PASSWORD}"
  }
}

Field	Required	Description
`connection_string`	No	Full connect string (alternative to individual fields, e.g. `host:1521/ORCL`)
`host`	No	Hostname (default: `127.0.0.1`)
`port`	No	Port (default: `1521`)
`service_name`	No	Oracle service name (default: `ORCL`)
`database`	No	Alias for `service_name`
`user`	No	Username
`password`	No	Password

Pure JavaScript driver

The Oracle driver uses oracledb in thin mode (pure JavaScript) — no Oracle Instant Client installation is required.

SQLite¶

{
  "dev-sqlite": {
    "type": "sqlite",
    "path": "./dev.sqlite"
  }
}

Field	Required	Description
`path`	Yes	Database file path, or `":memory:"` for in-memory. Cannot be omitted — a missing `path` is rejected rather than silently falling back to `":memory:"`
`readonly`	No	Open in read-only mode (default: `false`)
`create`	No	Create the database file if it is missing (default: `false`)

Note

SQLite uses Bun's built-in bun:sqlite driver. WAL journal mode is enabled automatically for writable databases.

The store must already exist

As with DuckDB, connecting never creates the database, and a relative path resolves against the directory of the config that declares it — not the current working directory. See the DuckDB section above for the full rules.

SQL Server¶

{
  "sqlserver-prod": {
    "type": "sqlserver",
    "host": "localhost",
    "port": 1433,
    "database": "analytics",
    "user": "sa",
    "password": "{env:MSSQL_PASSWORD}"
  }
}

Field	Required	Description
`host`	No	Hostname (default: `localhost`)
`port`	No	Port (default: `1433`)
`database`	No	Database name
`user`	No	Username
`password`	No	Password
`driver`	No	ODBC driver name (default: `ODBC Driver 18 for SQL Server`)
`azure_auth`	No	Use Azure AD authentication (default: `false`)
`trust_server_certificate`	No	Trust server certificate without validation (default: `false`)

Unsupported Databases¶

The following databases are not yet natively supported, but workarounds are available:

Database	Workaround
Cassandra	Use the bash tool with `cqlsh` to query directly
CockroachDB	PostgreSQL-compatible — use `type: postgres`
TimescaleDB	PostgreSQL extension — use `type: postgres`

SSH Tunneling¶

All warehouse types support SSH tunneling for connections behind a bastion host:

{
  "prod-via-bastion": {
    "type": "postgres",
    "host": "10.0.1.50",
    "database": "analytics",
    "user": "analyst",
    "password": "{env:PG_PASSWORD}",
    "ssh_host": "bastion.example.com",
    "ssh_port": 22,
    "ssh_user": "ubuntu",
    "ssh_auth_type": "key",
    "ssh_key_path": "~/.ssh/id_rsa"
  }
}

Field	Required	Description
`ssh_host`	Yes	SSH bastion hostname
`ssh_port`	No	SSH port (default: `22`)
`ssh_user`	Yes	SSH username
`ssh_auth_type`	No	`"key"` or `"password"`
`ssh_key_path`	No	Path to SSH private key
`ssh_password`	No	SSH password

Auto-Discovery¶

The /discover command can automatically detect warehouse connections from:

Source	Detection
dbt profiles	Searches for `profiles.yml` (see resolution order below)
Docker containers	Finds running PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, ClickHouse, and Trino containers
Environment variables	Scans for `SNOWFLAKE_ACCOUNT`, `PGHOST`, `DATABRICKS_HOST`, etc.

dbt profiles.yml resolution order¶

When discovering dbt profiles, altimate checks the following locations in priority order and uses the first one found:

Priority	Location	Description
1	Explicit path	If you pass a `path` parameter to the `dbt_profiles` tool
2	`DBT_PROFILES_DIR` env var	Standard dbt environment variable — set it to the directory containing your `profiles.yml`
3	Project-local `profiles.yml`	A `profiles.yml` in your dbt project root (next to `dbt_project.yml`)
4	`<home>/.dbt/profiles.yml`	The global default location (e.g., `~/.dbt/` on macOS/Linux, `%USERPROFILE%\.dbt\` on Windows)

This means teams that keep profiles.yml in their project repo (a common pattern for CI/CD) will have it detected automatically — no extra configuration needed.

# Option 1: Set the environment variable
export DBT_PROFILES_DIR=/path/to/your/project

# Option 2: Just put profiles.yml next to dbt_project.yml
# Copy from default location (macOS/Linux)
cp ~/.dbt/profiles.yml ./profiles.yml
altimate /discover

See Warehouse Tools for the full list of environment variable signals.

Testing Connections¶

After configuring a warehouse, verify it works:

> warehouse_test prod-snowflake

Testing connection to prod-snowflake (snowflake)...
  ✓ Connected successfully
  Account: xy12345.us-east-1
  User: analytics_user
  Role: ANALYST_ROLE
  Warehouse: COMPUTE_WH
  Database: ANALYTICS

Post-Connection Suggestions¶

After you successfully connect a warehouse, altimate suggests next steps to help you get the most out of your connection. Suggestions are shown progressively based on what you've already done:

Index your schemas — populate the schema cache for autocomplete and context-aware analysis
Run SQL analysis — scan your query history for anti-patterns and optimization opportunities
Inspect schema structure — review tables, columns, and relationships
Check lineage — trace column-level data flow across your models

If altimate detects a dbt project in your workspace, it also recommends relevant dbt skills (/dbt-develop, /dbt-troubleshoot, /dbt-analyze).

Each suggestion is shown once per session — dismissing or acting on a suggestion removes it from the queue. You can also run a suggested action later via its corresponding tool or slash command.