fix: address CodeRabbit review findings for ClickHouse driver PR

- Remove stale ClickHouse entry from "Unsupported Databases" doc section
- Add ClickHouse to Docker auto-discovery description in docs
- Add blank line around ClickHouse auth table for markdownlint MD058
- Add `text` language tag to fenced code block for markdownlint MD040
- Fail fast when `binds` passed to ClickHouse `execute()` instead of ignoring
- Add `tls_key`, `tls_cert`, `tls_ca_cert` to SENSITIVE_FIELDS in credential store
- Clamp `days`/`limit` values in ClickHouse query history SQL builder
- Add `clickhouse`, `clickhouse+http`, `clickhouse+https` to DATABASE_URL scheme map
- Make `waitForPort` accept configurable host in E2E tests
- Close failed connectors during `waitForDbReady` retries in E2E tests
- Add missing TLS alias tests: `ca_cert`, `ssl_cert`, `ssl_key`

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: anandgupta42

.claude/commands/add-database-driver.md

@@ -130,12 +130,12 @@ Work through all 9 phases from the checklist. Use parallel edits where possible.
 
 ```bash
 # Tests (from packages/opencode/)
-cd packages/opencode && bun test test/altimate/driver-normalize.test.ts test/altimate/connections.test.ts
+cd packages/opencode && bun test test/altimate/driver-normalize.test.ts test/altimate/connections.test.ts test/altimate/drivers-{database}-e2e.test.ts
 
-# Typecheck
-bun turbo typecheck
+# Typecheck (from repo root)
+cd "$(git rev-parse --show-toplevel)" && bun turbo typecheck
 
-# Marker check
+# Marker check (from repo root)
 bun run script/upstream/analyze.ts --markers --base main --strict
 ```
 

docs/docs/configure/warehouses.md

@@ -380,7 +380,6 @@ The following databases are not yet natively supported, but workarounds are avai
 
 | Database | Workaround |
 |----------|------------|
-| ClickHouse | Use the bash tool with `clickhouse-client` or `curl` to query directly |
 | Cassandra | Use the bash tool with `cqlsh` to query directly |
 | CockroachDB | PostgreSQL-compatible — use `type: postgres` |
 | TimescaleDB | PostgreSQL extension — use `type: postgres` |
@@ -422,7 +421,7 @@ The `/discover` command can automatically detect warehouse connections from:
 | Source | Detection |
 |--------|-----------|
 | dbt profiles | Parses `~/.dbt/profiles.yml` |
-| Docker containers | Finds running PostgreSQL, MySQL, and SQL Server containers |
+| Docker containers | Finds running PostgreSQL, MySQL, SQL Server, and ClickHouse containers |
 | Environment variables | Scans for `SNOWFLAKE_ACCOUNT`, `PGHOST`, `DATABRICKS_HOST`, etc. |
 
 See [Warehouse Tools](../data-engineering/tools/warehouse-tools.md) for the full list of environment variable signals.

docs/docs/drivers.md

@@ -136,6 +136,7 @@ altimate-dbt init --project-root /path/to/dbt/project --python-path $(which pyth
 | Password | `host`, `port`, `service_name`, `user`, `password` |
 
 ### ClickHouse
+
 | Method | Config Fields |
 |--------|--------------|
 | Password | `host`, `port`, `database`, `user`, `password` |

packages/drivers/ADDING_A_DRIVER.md

@@ -178,7 +178,7 @@ bun run script/upstream/analyze.ts --markers --base main --strict
 
 ## File Map
 
-```
+```text
 packages/drivers/
   src/
     {database}.ts          ← NEW: driver implementation

packages/drivers/src/clickhouse.ts

@@ -60,7 +60,10 @@ export async function connect(config: ConnectionConfig): Promise<Connector> {
       client = createClient(clientConfig)
     },
 
-    async execute(sql: string, limit?: number, _binds?: any[]): Promise<ConnectorResult> {
+    async execute(sql: string, limit?: number, binds?: any[]): Promise<ConnectorResult> {
+      if (binds && binds.length > 0) {
+        throw new Error("ClickHouse driver does not support parameterized binds — use ClickHouse query parameters instead")
+      }
       const effectiveLimit = limit === undefined ? 1000 : limit
       let query = sql
       // Only SELECT and WITH...SELECT support LIMIT — SHOW/DESCRIBE/EXPLAIN/EXISTS do not

packages/opencode/src/altimate/native/connections/credential-store.ts

@@ -31,6 +31,9 @@ const SENSITIVE_FIELDS = new Set([
   "ssl_key",
   "ssl_cert",
   "ssl_ca",
+  "tls_key",
+  "tls_cert",
+  "tls_ca_cert",
 ])
 
 /** Cached keytar module (or null if unavailable). */

packages/opencode/src/altimate/native/finops/query-history.ts

@@ -167,9 +167,11 @@ function buildHistoryQuery(
     return { sql: DATABRICKS_HISTORY_SQL, binds: [days, limit] }
   }
   if (whType === "clickhouse") {
-    const sql = CLICKHOUSE_HISTORY_SQL.replace("{days:UInt32}", String(Math.floor(Number(days)))).replace(
+    const clampedDays = Math.max(1, Math.min(Math.floor(Number(days)) || 30, 365))
+    const clampedLimit = Math.max(1, Math.min(Math.floor(Number(limit)) || 100, 10000))
+    const sql = CLICKHOUSE_HISTORY_SQL.replace("{days:UInt32}", String(clampedDays)).replace(
       "{limit:UInt32}",
-      String(Math.floor(Number(limit))),
+      String(clampedLimit),
     )
     return { sql, binds: [] }
   }

packages/opencode/src/altimate/tools/project-scan.ts

@@ -293,6 +293,9 @@ export async function detectEnvVars(): Promise<EnvVarConnection[]> {
       oracle: "oracle",
       duckdb: "duckdb",
       databricks: "databricks",
+      clickhouse: "clickhouse",
+      "clickhouse+http": "clickhouse",
+      "clickhouse+https": "clickhouse",
     }
     const dbType = schemeTypeMap[scheme] ?? "postgres"
     // Only add if we don't already have this type detected from other env vars

packages/opencode/test/altimate/driver-normalize.test.ts

@@ -902,6 +902,24 @@ describe("normalizeConfig — ClickHouse", () => {
     expect(result.ssl_ca).toBeUndefined()
   })
 
+  test("ca_cert → tls_ca_cert", () => {
+    const result = normalizeConfig({
+      type: "clickhouse",
+      ca_cert: "/path/to/ca.pem",
+    })
+    expect(result.tls_ca_cert).toBe("/path/to/ca.pem")
+    expect(result.ca_cert).toBeUndefined()
+  })
+
+  test("ssl_cert → tls_cert", () => {
+    const result = normalizeConfig({
+      type: "clickhouse",
+      ssl_cert: "/path/to/cert.pem",
+    })
+    expect(result.tls_cert).toBe("/path/to/cert.pem")
+    expect(result.ssl_cert).toBeUndefined()
+  })
+
   test("tlsCert → tls_cert", () => {
     const result = normalizeConfig({
       type: "clickhouse",
@@ -919,4 +937,13 @@ describe("normalizeConfig — ClickHouse", () => {
     expect(result.tls_key).toBe("/path/to/key.pem")
     expect(result.tlsKey).toBeUndefined()
   })
+
+  test("ssl_key → tls_key", () => {
+    const result = normalizeConfig({
+      type: "clickhouse",
+      ssl_key: "/path/to/key.pem",
+    })
+    expect(result.tls_key).toBe("/path/to/key.pem")
+    expect(result.ssl_key).toBeUndefined()
+  })
 })

packages/opencode/test/altimate/drivers-clickhouse-e2e.test.ts

@@ -22,11 +22,11 @@ function isDockerAvailable(): boolean {
   }
 }
 
-function waitForPort(port: number, timeout = 30000): Promise<void> {
+function waitForPort(port: number, timeout = 30000, host = "127.0.0.1"): Promise<void> {
   return new Promise((resolve, reject) => {
     const start = Date.now()
     const attempt = () => {
-      const sock = createConnection({ host: "127.0.0.1", port })
+      const sock = createConnection({ host, port })
       sock.once("connect", () => {
         sock.destroy()
         resolve()
@@ -55,13 +55,16 @@ async function waitForDbReady(
   const start = Date.now()
   let lastErr: any
   while (Date.now() - start < timeout) {
+    let connector: any
     try {
-      const { connector, testQuery } = await connectFn()
+      const result = await connectFn()
+      connector = result.connector
       await connector.connect()
-      await connector.execute(testQuery)
+      await connector.execute(result.testQuery)
       return connector
     } catch (e: any) {
       lastErr = e
+      try { connector?.disconnect?.() } catch {}
       await new Promise((r) => setTimeout(r, 2000))
     }
   }