clickhouse

Release clickhouse 0.15.1 / clickhouse-ext-arrow 0.1.0 (#438)

Added

• Introduced support for Apache Arrow in Rust via a new extension crate, clickhouse-ext-arrow. (#423)
  • The CHANGELOG for this new crate is tracked in ext-arrow/CHANGELOG.md.
  • See examples/arrow.rs for usage.
• Added BytesCursor::poll_next() (#423)

Fixed

• Variant columns containing NULL values no longer fail with a schema mismatch error. Use Option<MyEnum> to deserialize nullable Variant columns. (#400)
• Changed User-Agent header generation to use correct format for server-side logging/metrics. (#428)

Release 0.15.0 (#415)

Added

• Deprecated ::*_option() methods in favor of ::*_setting() (#380)
  • This is to match the terminology used by ClickHouse Server.
• Added support for zstd compression (#388)
• Added support for tracing and OpenTelemetry trace propagation to ClickHouse (#390)
  • See examples/opentelemetry.rs for usage.
• Exposed X-ClickHouse-Summary fields from server response (#397)
  • Added RowCursor::summary() and BytesCursor::summary() which is populated once the response from the server is received, containing potentially useful statistics about the query.

Changed

• Dropped abandoned fxhash and linked-hash-map dev-dependencies (#403)

feat: release 0.14.3 (#402)

Added

• Added support for SimpleAggregateFunction type (#394)

Fixed

• Fixed serialization of Option::None with Query::param() (#385)
• Fixed handling of Json type with type hints (#387)
• Fixed Insert for temporary tables and qualified table names (#391)
• Updated lz4_flex to get fix for RUSTSEC-2026-0041 (#396)

Release 0.14.2 (#378)

Added

• Added Client::insert_formatted_with() and InsertFormatted for inserting data in a chosen format with a specified SQL query. (#364)
  • InsertFormatted does not buffer data by default, allowing precise control over when the data is sent. For best performance, ensure data is sent in larger chunks or use .buffered() to get BufInsertFormatted which implements buffering.
  • Data may optionally be pre-compressed and buffered separately using CompressedData::new() and InsertFormatted::send_compressed().
  • BufInsertFormatted also implements tokio::io::AsyncWrite for composability.
• Added Client::set_option to modify options through &mut Client (#375)
• Added Client::get_option to read previously set options (#375)
• Added support for binding byte-strings as server-side params (#376)
  • This means passing types to Query::param that call Serializer::serialize_bytes() are now supported.
  • Note that Vec<u8> and &[u8] serialize as an array of integers. Use a specialized type, e.g. bytes::Bytes or serde_bytes::Bytes to bind a byte-string.
• Implemented Primitive for bytes::Bytes and bytes::BytesMut (#376)
  • These can be used to fetch byte-strings as a scalar value, e.g. with Query::fetch_one().

Fixed

• Implemented parsing for the new exception tagging format in ClickHouse 25.11 (#365)
• Fixed a doc comment on clickhouse::serde::chrono::date (#371)

Changed

• (CI-only change) added scheduled runs against clickhouse-server:head tag, reworked secrets access (#367)
• Query no longer sets the readonly option by default. (#377)
  • This was previously added in [#342] to simulate the default read-only restriction when issuing queries via GET requests, but had poor interaction with settings profiles that set readonly="2".

chore: Release clickhouse version 0.14.1

Added

• Implement Stream for RowCursor. (#283, #340)
• Added an optional on_commit callback to Inserter. (#307)
• Added with_role and with_default_roles methods to Client, Query, Insert, and Inserter, allowing to explicitly set the roles for executed queries. (#326)
• Added Int256 and UInt256 ClickHouse types support. The client now provides two new convenience wrappers over [u8; 32]: clickhouse::types::Int256 and clickhouse::types::UInt256. See the updated derive example. (#352)

Fixed

• When binding u128/i128 values to SQL queries using server-side params, the client now correctly serializes them as strings without adding an unnecessary cast. (#322)
• Fixed an issue where the schema validation could fail with custom JSON types such as JSON(max_dynamic_paths=64, max_dynamic_types=8). (#350, Steffen911)

Changed

• Optimize RowCursor by reusing buffer capacity where possible. (#340)
• All Query::fetch* methods will always use POST instead of GET. It is now allowed to change readonly value via Query::with_option. (#342)
• In case of a schema mismatch, the client now emits clickhouse::error::Error::SchemaMismatch instead of panicking. (#346)
• Removed replace_with, static_assertions, and sealed from the crate dependencies. (#353)

chore: Release clickhouse version 0.14.0

Removed

• BREAKING watch: Client::watch() API is removed (#245).
• BREAKING mock: watch() and watch_only_events() are removed (#245).

Changed

• BREAKING insert: the type of Insert<_> should now be specified when calling client.insert::<_>(). (#247)
• BREAKING insert: Client::insert() is now async. (#244)
• BREAKING inserter: Inserter::write() is now async. (#244)
• BREAKING inserter: Inserter::new() return just Self instead of Result<Self>. (#244)
• BREAKING query: RowBinaryWithNamesAndTypes is now used by default for query results. This may cause panics if the row struct definition does not match the database schema. Use Client::with_validation(false) to revert to the previous behavior which uses plain RowBinary format for fetching rows. (#221, #244)
• BREAKING mock: when using test-util feature, it is now required to use Client::with_mock(&mock) to set up the mock server, so it properly handles the response format and automatically disables parsing RowBinaryWithNamesAndTypes header parsing and validation. Additionally, it is not required to call with_url explicitly. See the updated example.
• BREAKING query: Query::fetch_bytes() now expects impl AsRef<str> for format instead of Into<String>. Most usages should not be affected, however, unless passing a custom type that implements the latter but not the former. (#311)
• query: due to RowBinaryWithNamesAndTypes format usage, there might be an impact on fetch performance, which largely depends on how the dataset is defined. If you notice decreased performance, consider disabling validation by using Client::with_validation(false).
• serde: it is now possible to deserialize Map ClickHouse type into HashMap<K, V> (or BTreeMap, IndexMap, DashMap, etc.).
• tls: improved error messages in case of missing TLS features when using HTTPS (#229).
• crate: MSRV is now 1.79 due to borrowed rows support redesign in #247.
• crate: bumped dependencies, see #232, #239 and #280 for additional details.
• crate: starting from 0.3.0, clickhouse-derive is now published as clickhouse-macros on crates.io. The former clickhouse-derive crate is discontinued. (#318).

Added

• types: added support for Time and Time64 types (#258).
• client: added Client::with_validation builder method. Validation is enabled by default, meaning that RowBinaryWithNamesAndTypes format will be used to fetch rows from the database. If validation is disabled, RowBinary format will be used, similarly to the previous versions. (#221).
• 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).
• query: support serializing serde_bytes::Bytes as hex string literals in query parameters (#250).
• derive: added #[clickhouse(crate = "...")] attribute for #[derive(Row)] (#189, #292)

Fixed

• client: extract the exception code from X-ClickHouse-Exception-Code in case of incorrect 200 OK response that could occur with ClickHouse server up to versions 24.x (#256).
• query: pass format as ?default_format URL parameter instead of using FORMAT clause, allowing queries to have trailing comments and/or semicolons (#267, #269, #311).

chore: Release clickhouse version 0.13.3

Added

• client: added Client::with_access_token to support JWT authentication ClickHouse Cloud feature (#215).
• Identifier: added Copy and Clone derive (#224).

Fixed

• query/cursor: detect more deferred errors (#220).
• query/bind: fixed i128/u128 SQL serialization (#209).

chore: Release clickhouse version 0.13.2

Added

• query: added Query::with_param to support server-side parameters binding (#159)
• derive: added Variant data type support (#170).
• query: added Query::fetch_bytes that allows streaming data in an arbitrary format (#182)
• serde: added support for chrono (#188)

Changed

• MSRV is now 1.73 due to changes in bstr and hyper-rustls dependencies (#180).

Fixed

• query/cursor: return NotEnoughData if a row is unparsed when the stream ends (#185).

chore: Release clickhouse version 0.13.1

Added

• query/cursor: add RowCursor::{decoded_bytes,received_bytes} methods (#169).

Changed

• query/cursor: improve performance of RowCursor::next() (#169).

Fixed

• mock: work with the advanced time via tokio::time::advance() (#165).

Added

• query: add Query::sql_display() (#155).
• client: add Client::with_product_info() (#135).
• client: add the User-Agent header to all requests (#135).

Changed

• MSRV is now 1.70 due to changes in hyper-rustls v0.27.3.
• tls: revise HTTPS-related features, see README for details (#140,#141,#156).
• query: support ?? for escaping the ? symbol in SQL (#154).

Fixed

• insert: don't panic on empty inserts (#139).
• uuid: serialization in human-readable formats (#76).

Changed

• Now this crate is pure Rust, no more C/C++ dependencies.
• insert: increase max size of frames to improve throughput (#130).
• compression: replace lz4 sys binding with lz4-flex (pure Rust).
• compression: replace clickhouse-rs-cityhash-sys sys binding with cityhash-rs (pure Rust) (#107).

Deprecated

• compression: Compression::Lz4Hc is deprecated and becomes an alias to Compression::Lz4.

Added

• query/bind: support Option in query.bind(arg) (#119, #120).
• client: Client::with_header() to provide custom headers (#98, #108).
• query: added Query::with_option() similar to Client::with_option() (#123).
• insert: added Insert::with_option() similar to Client::with_option() (#123).
• inserter: added Inserter::with_option() similar to Client::with_option() (#123).

Changed

• insert: the outgoing request is now created after the first Insert::write call instead of Insert::new (#123).

Added

• derive: support serde::skip_deserializing (#83).
• insert: apply options set on the client (#90).
• inserter: can be limited by size, see Inserter::with_max_bytes().
• inserter: Inserter::pending() to get stats about still being inserted data.
• inserter: Inserter::force_commit() to commit and insert immediately.
• mock: impl Default instance for Mock.

Changed

• BREAKING bump MSRV to 1.67.
• BREAKING replace the tls feature with native-tls and rustls-tls that must be enabled explicitly now.
• BREAKING http: HttpClient API is changed due to moving to hyper v1.
• BREAKING inserter: move under the inserter feature.
• BREAKING inserter: there is no default limits anymore.
• BREAKING inserter: Inserter::write is synchronous now.
• BREAKING inserter: rename entries to rows.
• BREAKING drop the wa-37420 feature.
• BREAKING remove deprecated items.
• BREAKING mock: provide(), watch() and watch_only_events() now accept iterators instead of streams.
• inserter: improve performance of time measurements by using quanta.
• inserter: improve performance if the time limit isn't used.
• derive: move to syn v2.
• mock: return a request if no handler is installed (#89, #91).

Fixed

• watch: support a new syntax.
• uuid: possible unsoundness.
• query: avoid panics during Query::bind() calls (#103).

Fixed

• client: accept HTTPs urls if tls feature is enabled (#58).

Changed

• inserter: start new insert only when the first row is provided (#68, #70).

Added

• query: Query::fetch_optional().

Changed

• query: increase performance up to 40%.

Added

• client: support HTTPS (#54).

Changed

• query: improve throughput (~8%).

Fixed

• cursor: handle errors sent at the end of a response (#56).

Added

• insert: with_timeouts to manage timeouts.
• inserter: with_timeouts and set_timeouts to manage timeouts.

Changed

• insert: improve throughput (~30%).
• inserter: set a default value of max_entries to 500_000.

Added

• ipv4: serde::ipv4 for ser/de the IPv4 type to/from Ipv4Addr. Note that IPv6 requires no annotations.
• time: serde::time::datetime(64) for ser/de the time::OffsetDateTime type to/from DateTime and DateTime64.
• time: serde::time::date(32) for ser/de the time::Date type to/from Date and Date32.
• serde: add ::option variants to support Option<_>.

Changed

• uuid: move to the serde submodule.

Added

• compression: implement Lz4/Lz4Hc compression modes for INSERTs (#39).
• insert: the wa-37420 feature to avoid ClickHouse#37420.
• inserter: new method Inserter::time_left().
• uuid: the uuid feature and a corresponding module to ser/de uuid::Uuid (#26).

Changed

• BREAKING decompression: HTTP compression (gzip, zlib and brotli) isn't available anymore, only Lz4.
• inserter: skip timer ticks if INSERT is too long (#20).

Added

• client: Client::with_http_client to use custom hyper::Client, e.g. for https (#27).

Changed

• watch: run WATCH queries with max_execution_time=0.
• bind: implement Bind for all Serialize instances (#33).

Fixed

• Implement Primitive for f64 (#31).

Added

• Implement Primitive for f64 and f32 (#29).

Fixed

• Reset quantities on errors to support reusing Inserter after errors (#30).

Changed

• HTTP Keep-alive timeout is restricted to 2s explicitly.

Fixed

• watch: make a cursor cancellation safe.

Added

• mock: add record_ddl handler to test DDL queries.
• mock: add watch and watch_only_events handlers to test WATCH queries.

Fixed

• query: support borrowed long strings (#22).
• query: read the whole response of DDL queries.

Changed

• BREAKING: watch: require the watch feature.
• BREAKING: watch: only struct rows are allowed because JSON requires names.
• query: queries with invalid URLs fail with Error::InvalidParams.
• watch: use JSONEachRowWithProgress because of ClickHouse#22996 (#23).

Fixed

• Support ? inside bound arguments (#18).
• Use the POST method if a query is bigger than 8KiB (#19).

Fixed

• RowBinarySerializer::is_human_readable() returns false.

Added

• Watch::refresh() to specify REFRESH clause.

Fixed

• derive(Row): handle raw identifiers.

Fixed

• Get rid of "socket is not connected" errors.

Changed

• Set TCP keepalive to 60 seconds.

Changed

• Replace reflection::Reflection with clickhouse::Row. It's enough to implement Row for top-level structs only.

Added

• #[derive(Row)]

Fixed

• docs: enable the doc_cfg feature.

Fixed

• docs: show features on docs.rs.
• Now test-util implies hyper/server.

Added

• test module (available with the test-util feature).
• #[must_use] for Query, Watch, Insert and Inserter.

Added

• &String values binding to SQL queries.

Fixed

• Depend explicitly on tokio/macros.

Added

• Support for bool values storage (#9).
• arrays' binding to SQL queries — useful at IN operators, etc (#9).
• String values binding to SQL queries (#9).
• Query::fetch_all()
• sql::Identifier

Changed

• Expose query::Bind (#11).
• Deprecate Compression::encoding().

Fixed

• watch: bind fileds of the type param.

Fixed

• compression: decompress error messages (#7).

Changed

• Use tokio v1, hyper v0.14, bytes v1.

Added

• decompression: lz4.

Added

• decompression: gzip, zlib and brotli.

Added

• Query::fetch_one(), Watch::fetch_one().
• Query::fetch() as a replacement for Query::rows().
• Watch::fetch() as a replacement for Watch::rows().
• Watch::only_events().fetch() as a replacement for Watch::events().

Changed

• Error is StdError + Send + Sync + 'static now.

Added

• Expose cursors (query::RowCursor, watch::{RowCursor, EventCursor}).

Added

• Client::inserter() for infinite inserting into tables.
• Client::watch() for LIVE VIEW related queries.

Changed

• Renamed Query::fetch() to Query::rows().
• Use GET requests for SELECT statements.

Added

• Support basic types.
• Client::insert() for inserting into tables.
• Client::query() for selecting from tables and DDL statements.

<!-- next-url --> [Unreleased]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.15.1...HEAD [0.15.1]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.15.0...v0.15.1 [0.15.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.14.3...v0.15.0 [0.14.3]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.14.2...v0.14.3 [0.14.2]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.14.1...v0.14.2 [0.14.1]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.14.0...v0.14.1 [0.14.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.13.3...v0.14.0 [0.13.3]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.13.2...v0.13.3 [0.13.2]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.13.1...v0.13.2 [0.13.1]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.13.0...v0.13.1 [0.13.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.12.2...v0.13.0 [0.12.2]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.12.1...v0.12.2 [0.12.1]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.12.0...v0.12.1 [0.12.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.11.6...v0.12.0 [0.11.6]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.11.5...v0.11.6 [0.11.5]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.11.4...v0.11.5 [0.11.4]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.11.3...v0.11.4 [0.11.3]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.11.2...v0.11.3 [0.11.2]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.11.1...v0.11.2 [0.11.1]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.11.0...v0.11.1 [0.11.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.10.0...v0.11.0 [0.10.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.9.3...v0.10.0 [0.9.3]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.9.2...v0.9.3 [0.9.2]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.9.1...v0.9.2 [0.9.1]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.9.0...v0.9.1 [0.9.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.8.1...v0.9.0 [0.8.1]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.8.0...v0.8.1 [0.8.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.7.2...v0.8.0 [0.7.2]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.7.1...v0.7.2 [0.7.1]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.7.0...v0.7.1 [0.7.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.6.8...v0.7.0 [0.6.8]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.6.7...v0.6.8 [0.6.7]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.6.6...v0.6.7 [0.6.6]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.6.5...v0.6.6 [0.6.5]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.6.4...v0.6.5 [0.6.4]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.6.3...v0.6.4 [0.6.3]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.6.2...v0.6.3 [0.6.2]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.6.1...v0.6.2 [0.6.1]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.6.0...v0.6.1 [0.6.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.5.1...v0.6.0 [0.5.1]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.5.0...v0.5.1 [0.5.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.4.0...v0.5.0 [0.4.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.3.0...v0.4.0 [0.3.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.2.0...v0.3.0 [0.2.0]: https://github.com/ClickHouse/clickhouse-rs/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/ClickHouse/clickhouse-rs/releases/tag/v0.1.0