Crate klickhouse

source ·
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.

Modules§

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§

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§

Type Aliases§

Derive Macros§

  • Row
    Derive macro for the Row trait.