Incident response · Root cause analysis
Diagnosing a JDBC protocol regression after a ClickHouse upgrade
Traced a Tableau Custom SQL failure to ClickHouse response-format precedence and shipped a targeted connector workaround while upstream fixed the Java driver.
- Organization
- Jet Games FZ-LLC
- Period
- Sep 2026
Symptom
After moving ClickHouse to 26.8, Tableau Server's Custom SQL stopped working during schema discovery. Ordinary query debugging did not explain the mismatch.
Investigation
Found a protocol-level incompatibility: the server gave precedence to X-ClickHouse-Format, so the JDBC v2 driver path received RowBinary instead of the TSKV format the connector expected. Matched the behavior with the clickhouse-java upstream issue and its merged fix.
Workaround
Patched the packaged Tableau .taco connector: connectionBuilder.js forces clickhouse.jdbc.v1=true, the plugin version went from 0.2.6 to 0.2.7, and the connector is registered through tsm native_api.connect_plugins_path. The legacy driver path brought a separate schema-discovery issue, handled with databaseTerm=schema. Documented the rollback: remove the custom connector and restart Tableau Server.
Outcome
Custom SQL in Tableau works again without downgrading the whole ClickHouse cluster.
Trade-offs and limitations
A workaround for these specific versions, not a recommendation to use JDBC v1. For current deployments, check the supported connector and driver versions first.
Technologies
- ClickHouse 26.8
- Tableau Server
- JDBC
- clickhouse-java
- HTTP