clickhouse-rust-type-mismatches

ClickHouse-Rust Type Mismatches

Problem

When using the clickhouse-rs Rust crate with ClickHouse, deserialization errors occur due to type mismatches between the database schema and Rust struct definitions.

Context / Trigger Conditions

• Error: "string is not valid utf8" when querying String columns
• Error: "tag for enum is not valid" when deserializing rows
• Error: "not enough data, probably a row type mismatches a database schema" when deserializing rows
• Using #[derive(Row)] from clickhouse crate
• Views that use LEFT JOIN or aggregate functions
• Multiple query functions sharing the same Row struct but with different SELECT lists

Root Causes

0. Column Count Mismatch ("not enough data")

When multiple query functions share the same #[derive(Row)] struct, adding new fields to the struct and some queries but forgetting to update OTHER queries that use the same struct causes "not enough data" deserialization errors. The query returns fewer columns than the struct expects.

Symptoms:

• Error: "not enough data, probably a row type mismatches a database schema"
• One query function works, another fails, both using the same Row struct
• Error is misleading — suggests DB schema issue but is actually a code bug

Debugging:

1. Count the fields in the Rust Row struct
2. Count the SELECT columns in the failing query
3. Compare with the working query — look for missing columns
4. Often caused by adding fields (like subtitle/text-track columns) to the struct and one query but forgetting to update a secondary query (e.g., get_by_id updated but get_by_d_tag forgotten)

Fix: Add the missing SELECT columns to the failing query to match the struct:

// Both queries must select the SAME columns in the SAME order as the struct
// If struct has 17 fields, every query using it must SELECT 17 columns

1a. FixedString vs String (SELECT / Deserialization)

ClickHouse FixedString(N) pads with null bytes. These don't deserialize cleanly as UTF-8 strings in Rust.