feat(derive): support #[clickhouse(crate = "...")] (#292)

Co-authored-by: Anton Parfonov <[email protected]>
Co-authored-by: YBoy <[email protected]>
Co-authored-by: Philip Dubé <[email protected]>

Author: 4 people

CHANGELOG.md

@@ -36,9 +36,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - types: a new crate `clickhouse-types` was added to the project workspace. This crate is required for
   `RowBinaryWithNamesAndTypes` struct definition validation, as it contains ClickHouse data types AST, as well as
   functions and utilities to parse the types out of the ClickHouse server response. ([#221]).
+- derive: added `#[clickhouse(crate = "...")]` attribute for `#[derive(Row)]` ([#189]/[#292])
 
+[#189]: https://github.com/ClickHouse/clickhouse-rs/pull/189
 [#221]: https://github.com/ClickHouse/clickhouse-rs/pull/221
 [#245]: https://github.com/ClickHouse/clickhouse-rs/pull/245
+[#292]: https://github.com/ClickHouse/clickhouse-rs/pull/292
 
 ## [0.13.3] - 2025-05-29
 ### Added

derive/src/attributes.rs

@@ -0,0 +1,52 @@
+use syn::meta::ParseNestedMeta;
+
+pub struct Attributes {
+    pub crate_path: syn::Path,
+}
+
+impl Default for Attributes {
+    fn default() -> Self {
+        Attributes {
+            // Note: changing this to `::clickhouse` is likely a breaking change;
+            // it's possible that the user has renamed the `clickhouse` package,
+            // but then aliased it back to `clickhouse` to fix the derive.
+            crate_path: syn::parse_str("clickhouse").expect("BUG: crate_path should parse"),
+        }
+    }
+}
+
+impl TryFrom<&[syn::Attribute]> for Attributes {
+    type Error = syn::Error;
+
+    fn try_from(attrs: &[syn::Attribute]) -> syn::Result<Self> {
+        for attr in attrs {
+            if attr.path().is_ident("clickhouse") {
+                let mut out = Attributes::default();
+
+                attr.parse_nested_meta(|meta| parse_nested_meta(meta, &mut out))?;
+
+                return Ok(out);
+            }
+        }
+
+        Ok(Self::default())
+    }
+}
+
+/// Called for each meta-item inside the `#[clickhouse(...)]` attribute.
+fn parse_nested_meta(meta: ParseNestedMeta<'_>, out: &mut Attributes) -> syn::Result<()> {
+    // #[clickhouse(crate = "<path>")]
+    if meta.path.is_ident("crate") {
+        out.crate_path = meta
+            // Expect and eat the `=` token
+            .value()?
+            // Expect a string literal like Serde: https://serde.rs/container-attrs.html#crate
+            .parse::<syn::LitStr>()?
+            // Parse the literal content as `Path`
+            .parse()?;
+    } else {
+        return Err(meta.error("unexpected `#[clickhouse(...)]` argument"));
+    }
+
+    Ok(())
+}

derive/src/lib.rs

@@ -1,3 +1,4 @@
+use crate::attributes::Attributes;
 use proc_macro2::{Span, TokenStream};
 use quote::quote;
 use serde_derive_internals::{
@@ -6,9 +7,21 @@ use serde_derive_internals::{
 };
 use syn::{parse_macro_input, Data, DataStruct, DeriveInput, Error, Fields, Lifetime, Result};
 
+mod attributes;
+
 #[cfg(test)]
 mod tests;
 
+// TODO: support wrappers `Wrapper(Inner)` and `Wrapper<T>(T)`.
+// TODO: support the `nested` attribute.
+#[proc_macro_derive(Row, attributes(clickhouse))]
+pub fn row(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    row_impl(input)
+        .unwrap_or_else(Error::into_compile_error)
+        .into()
+}
+
 fn column_names(data: &DataStruct, cx: &Ctxt, container: &Container) -> Result<TokenStream> {
     Ok(match &data.fields {
         Fields::Named(fields) => {
@@ -36,19 +49,11 @@ fn column_names(data: &DataStruct, cx: &Ctxt, container: &Container) -> Result<T
     })
 }
 
-// TODO: support wrappers `Wrapper(Inner)` and `Wrapper<T>(T)`.
-// TODO: support the `nested` attribute.
-// TODO: support the `crate` attribute.
-#[proc_macro_derive(Row)]
-pub fn row(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
-    let input = parse_macro_input!(input as DeriveInput);
-    row_impl(input)
-        .unwrap_or_else(Error::into_compile_error)
-        .into()
-}
-
 fn row_impl(input: DeriveInput) -> Result<TokenStream> {
     let cx = Ctxt::new();
+
+    let Attributes { crate_path } = input.attrs[..].try_into()?;
+
     let container = Container::from_ast(&cx, &input);
     let name = input.ident;
 
@@ -89,14 +94,13 @@ fn row_impl(input: DeriveInput) -> Result<TokenStream> {
 
     let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
 
-    // TODO: replace `clickhouse` with `::clickhouse` here.
     Ok(quote! {
         #[automatically_derived]
-        impl #impl_generics clickhouse::Row for #name #ty_generics #where_clause {
+        impl #impl_generics #crate_path::Row for #name #ty_generics #where_clause {
             const NAME: &'static str = stringify!(#name);
             const COLUMN_NAMES: &'static [&'static str] = #column_names;
-            const COLUMN_COUNT: usize = <Self as clickhouse::Row>::COLUMN_NAMES.len();
-            const KIND: clickhouse::_priv::RowKind = clickhouse::_priv::RowKind::Struct;
+            const COLUMN_COUNT: usize = <Self as #crate_path::Row>::COLUMN_NAMES.len();
+            const KIND: #crate_path::_priv::RowKind = #crate_path::_priv::RowKind::Struct;
 
             type Value<'__v> = #value;
         }

derive/src/tests/cases.rs

@@ -14,7 +14,7 @@ fn simple_owned_row() {
             a: i32,
             b: String,
         }
-    };
+    }
 }
 
 #[test]
@@ -25,23 +25,23 @@ fn generic_owned_row() {
             a: i32,
             b: T,
         }
-    };
+    }
 
     render! {
         #[derive(Row)]
         struct Sample<A, B> {
             a: A,
             b: B,
         }
-    };
+    }
 
     render! {
         #[derive(Row)]
         struct Sample<T> where T: Clone {
             a: i32,
             b: T,
         }
-    };
+    }
 }
 
 #[test]
@@ -52,7 +52,7 @@ fn simple_borrowed_row() {
             a: i32,
             b: &'a str,
         }
-    };
+    }
 }
 
 #[test]
@@ -63,23 +63,23 @@ fn generic_borrowed_row() {
             a: i32,
             b: &'a T,
         }
-    };
+    }
 
     render! {
         #[derive(Row)]
         struct Sample<'a, A, B> {
             a: A,
             b: &'a B,
         }
-    };
+    }
 
     render! {
         #[derive(Row)]
         struct Sample<'a, T> where T: Clone {
             a: i32,
             b: &'a T,
         }
-    };
+    }
 }
 
 #[test]
@@ -93,7 +93,7 @@ fn serde_rename() {
             #[serde(rename = "items.b")]
             items_b: Vec<u32>,
         }
-    };
+    }
 }
 
 #[test]
@@ -105,7 +105,7 @@ fn serde_skip_serializing() {
             #[serde(skip_serializing)]
             b: u32,
         }
-    };
+    }
 }
 
 #[test]
@@ -117,5 +117,17 @@ fn serde_skip_deserializing() {
             #[serde(skip_deserializing)]
             b: u32,
         }
-    };
+    }
+}
+
+#[test]
+fn crate_attribute() {
+    render! {
+        #[derive(Row)]
+        #[clickhouse(crate = "foo")]
+        struct Foo {
+            a: u32,
+            b: u32,
+        }
+    }
 }

derive/src/tests/snapshots/crate_attribute.snap

@@ -0,0 +1,20 @@
+---
+source: derive/src/tests/cases.rs
+assertion_line: 125
+---
+#[derive(Row)]
+#[clickhouse(crate = "foo")]
+struct Foo {
+    a: u32,
+    b: u32,
+}
+
+/****** GENERATED ******/
+#[automatically_derived]
+impl foo::Row for Foo {
+    const NAME: &'static str = stringify!(Foo);
+    const COLUMN_NAMES: &'static [&'static str] = &["a", "b"];
+    const COLUMN_COUNT: usize = <Self as foo::Row>::COLUMN_NAMES.len();
+    const KIND: foo::_priv::RowKind = foo::_priv::RowKind::Struct;
+    type Value<'__v> = Self;
+}

src/lib.rs

@@ -10,7 +10,10 @@ pub use self::{
     row::{Row, RowOwned, RowRead, RowWrite},
 };
 use self::{error::Result, http_client::HttpClient};
+
+#[doc = include_str!("row_derive.md")]
 pub use clickhouse_derive::Row;
+
 use std::{collections::HashMap, fmt::Display, sync::Arc};
 
 pub mod error;

src/row.rs

@@ -13,15 +13,17 @@ pub enum RowKind {
 /// Represents a row that can be used in queries.
 ///
 /// Implemented for:
-/// * All `#[derive(Row)]` items
+/// * All [`#[derive(Row)]`][row-derive] items
 /// * `(P1, P2, ...)` where P* is a primitive type or string
 ///
-/// Do not implement this trait directly, use `#[derive(Row)]` instead.
+/// Do not implement this trait directly, use [`#[derive(Row)]`][row-derive] instead.
 ///
 /// In order to write a generic code over rows, check
 /// * [`RowRead`] for reading queries.
 /// * [`RowWrite`] for writing queries.
 /// * [`RowOwned`] for rows that do not hold any references.
+///
+/// [row-derive]: derive@crate::Row
 pub trait Row {
     // NOTE: all properties are unstable and, hence, not following semver.
 
@@ -277,21 +279,21 @@ pub(crate) fn join_column_names<R: Row>() -> Option<String> {
 
 #[cfg(test)]
 mod tests {
-    // XXX: need for `derive(Row)`. Provide `row(crate = ..)` instead.
-    use crate as clickhouse;
-    use clickhouse::Row;
+    use crate::Row;
 
     use super::*;
 
     #[test]
     fn it_grabs_simple_struct() {
         #[derive(Row)]
+        #[clickhouse(crate = "crate")]
         #[allow(dead_code)]
         struct Simple1 {
             one: u32,
         }
 
         #[derive(Row)]
+        #[clickhouse(crate = "crate")]
         #[allow(dead_code)]
         struct Simple2 {
             one: u32,
@@ -305,6 +307,7 @@ mod tests {
     #[test]
     fn it_grabs_mix() {
         #[derive(Row)]
+        #[clickhouse(crate = "crate")]
         struct SomeRow {
             _a: u32,
         }
@@ -317,6 +320,7 @@ mod tests {
         use serde::Serialize;
 
         #[derive(Row, Serialize)]
+        #[clickhouse(crate = "crate")]
         #[allow(dead_code)]
         struct TopLevel {
             #[serde(rename = "two")]
@@ -331,6 +335,7 @@ mod tests {
         use serde::Serialize;
 
         #[derive(Row, Serialize)]
+        #[clickhouse(crate = "crate")]
         #[allow(dead_code)]
         struct TopLevel {
             one: u32,
@@ -346,6 +351,7 @@ mod tests {
         use serde::Deserialize;
 
         #[derive(Row, Deserialize)]
+        #[clickhouse(crate = "crate")]
         #[allow(dead_code)]
         struct TopLevel {
             one: u32,
@@ -360,6 +366,7 @@ mod tests {
     fn it_rejects_other() {
         #[allow(dead_code)]
         #[derive(Row)]
+        #[clickhouse(crate = "crate")]
         struct NamedTuple(u32, u32);
 
         assert_eq!(join_column_names::<u32>(), None);
@@ -372,6 +379,7 @@ mod tests {
         use serde::Serialize;
 
         #[derive(Row, Serialize)]
+        #[clickhouse(crate = "crate")]
         #[allow(dead_code)]
         struct MyRow {
             r#type: u32,