Crate klickhouse

Expand description

§Klickhouse

Klickhouse is a pure Rust SDK for working with Clickhouse with the native protocol in async environments with minimal boilerplate and maximal performance.

§Example Usage

See example usage.

§Unsupported Features

Clickhouse Enum8 and Enum16 types – use LowCardinality instead.

§Running the tests

A Clickhouse server is required to run the integration tests. One can be started easily in a Docker container:

$ docker run  --rm --name clickhouse -p 19000:9000 --ulimit nofile=262144:262144 clickhouse
$ export KLICKHOUSE_TEST_ADDR=127.0.0.1:19000
$ # export KLICKHOUSE_TEST_USER=default
$ # export KLICKHOUSE_TEST_PASSWORD=default
$ # export KLICKHOUSE_TEST_DATABASE=default
$ cargo nextest run

(running the tests simultaneously with cargo test is currently not suported, due to loggers initializations.)

§Feature flags

derive: Enable klickhouse_derive, providing a derive macro for the Row trait. Default.
compression: lz4 compression for client/server communication. Default.
serde: Derivation of serde::Serialize and serde::Deserialize on various objects, and JSON support. Default.
tls: TLS support via tokio-rustls.
refinery: Migrations via refinery.
geo-types: Conversion of geo types to/from the geo-types crate.
bb8: Enables a ConnectionManager managed by bb8

§Credit

klickhouse_derive was made by copy/paste/simplify of serde_derive to get maximal functionality and performance at lowest time-cost. In a prototype, serde was directly used, but this was abandoned due to lock-in of serde’s data model.

Re-exports§

pub use bb8;

Modules§

block
query_parser

Structs§

Bytes: Wrapper over Vec to allow more efficient serialization/deserialization of raw bytes The corresponding Clickhouse type here is String or FixedString, not Array(UInt8). Conversion to Array(UInt8) will happen, but it is not efficient.
ClickhouseLock: A hack implementation of a global lock for things like migrations
Client: Client handle for a Clickhouse connection, has internal reference to connection, and can be freely cloned and sent across threads.
ClientOptions: Options set for a Clickhouse connection.
ClusterMigration: Wrapper for Client to use migrations on clusters
ConnectionManager
Date: Wrapper type for Clickhouse Date type.
DateTime: Wrapper type for Clickhouse DateTime type.
DateTime64: Wrapper type for Clickhouse DateTime64 type.
DynDateTime64: Wrapper type for Clickhouse DateTime64 type with dynamic precision.
FixedPoint32: Wrapper type for Clickhouse FixedPoint32 type.
FixedPoint64: Wrapper type for Clickhouse FixedPoint64 type.
FixedPoint128: Wrapper type for Clickhouse FixedPoint128 type.
FixedPoint256: Wrapper type for Clickhouse FixedPoint256 type.
IndexMap: A hash table where the iteration order of the key-value pairs is independent of the hash values of the keys.
Ipv4: Wrapper type for Clickhouse IPv4 type.
Ipv6: Wrapper type for Clickhouse IPv6 type.
Json: A Vec wrapper that is encoded as a tuple in SQL as opposed to a Vec
MultiPolygon: Union of polygons.
ParsedQuery
Point: Geo point, represented by its x and y coordinates.
Polygon: Polygon with holes. The first element is the outer polygon, and the following ones are the holes.
Progress: Query execution progress. Values are delta and must be summed.
QueryBuilder
RawRow: A row of raw data returned from the database by a query. Or an unstructured runtime-defined row to upload to the server.
Ring: Polygon without holes.
SelectBuilder
UnitValue: A single column row
Uuid: A Universally Unique Identifier (UUID).
VecTuple: A Vec wrapper that is encoded as a tuple in SQL as opposed to a Vec
i256: Wrapper type for Clickhouse Int256 type.
u256: Wrapper type for Clickhouse UInt256 type.

Enums§

KlickhouseError
Type: A raw Clickhouse type.
Tz: TimeZones built at compile time from the tz database
Value: A raw Clickhouse value. Types are not strictly/completely preserved (i.e. types String and FixedString both are value String). Use this if you want dynamically typed queries.

Constants§

VERSION_MAJOR: Clickhouse major version
VERSION_MINOR: Clickhouse minor version

Traits§

ClusterName
FromSql: A type that can be converted from a raw Clickhouse SQL value.
Row: A row that can be deserialized and serialized from a raw Clickhouse SQL value. Generally this is not implemented manually, but using klickhouse_derive::Row. I.e. #[derive(klickhouse::Row)].
RowIndex
ToSql: A type that can be converted to a raw Clickhouse SQL value.

Functions§

unexpected_type

Type Aliases§

Result

Derive Macros§

Row: Derive macro for the Row trait.

Crate klickhouseCopy item path