Crate clickhouse_c

Expand description

Rust bindings for clickhouse-c.

Crate reads and writes ClickHouse Native blocks and implements native TCP protocol. API has three layers:

sys exposes unsafe C API.
BlockReader, BlockBuilder, Client, and related types provide safe block and protocol operations.
PosixIo, AsyncClient, and tls provide transport adapters.

§Entry points

Use BlockReader and BlockBuilder for Native block streams over any Io implementation.
Use Client for blocking native TCP protocol.
Use IolessClient to process protocol bytes with caller-managed I/O.
Enable tokio feature and use AsyncClient for asynchronous TCP.
Enable tls feature and use tls::TlsIo or AsyncClient::connect_tls for rustls connections.

§Safety model

Safe API depends on invariants documented by bundled clickhouse-c revision, available as UPSTREAM_REVISION. Slice lengths are bounded by owning C values.

Decoding does not automatically validate relationships between nested columns. Call Block::validate before using offsets or dictionary keys from untrusted input as indexes.

Types containing self-references, including PosixIo, Codec, and tls::TlsIo, return Pin<Box<Self>>. Owning handles implement Send. Connection handles do not implement Sync.

Modules§

sys: Raw FFI bindings for clickhouse-c.
tls: Rustls transport support.

Structs§

Allocator: Allocator used for memory owned by clickhouse-c.
AsyncClient: Asynchronous ClickHouse native protocol client.
Block: Decoded Native block.
BlockBuilder: Native block assembled from borrowed column data.
BlockOpts: Options that describe Native block framing.
BlockReader: Reads consecutive Native Block values from an Io implementation.
CancelToken: Cooperative read cancellation for PosixIo.
Client: Active blocking ClickHouse connection.
ClientOpts: Client settings sent during Hello handshake.
Codec: Compression callbacks used by clickhouse-c.
Column: Borrowed view of a block column.
ColumnBuilder: Column descriptor over borrowed data.
Error: Error returned by this crate.
Exception: Exception returned by ClickHouse server.
IolessClient: Native protocol client without transport I/O.
LowCardinalityView: Borrowed parts of a LowCardinality column.
PosixIo: Blocking Io implementation for a Unix file descriptor.
ProfileInfo: Query totals reported near completion.
Progress: Incremental query counters. Each packet contains a delta.
QueryOpts: Additional values sent by Client::send_query_with.
QueryParam: Value for a {name:Type} query parameter.
QuerySetting: Query setting sent to ClickHouse.
ServerInfo: Server information received during Hello handshake.
SliceIo: Read-only transport over a borrowed byte slice.
TypeAst: Parsed ClickHouse type.
TypeRef: Borrowed view of a ClickHouse type.

Enums§

ColumnLayout: Storage layout of a decoded column.
Compression: Compression algorithm used for native protocol frames.
ErrorKind: Category corresponding to a clickhouse-c CHC_ERR_* code.
Event: Event received from server.
IntervalUnit: Unit of an Interval type.
Kind: ClickHouse type kind.
PacketKind: Server packet kind.
Step: Result of a protocol operation that may require more input.

Constants§

UPSTREAM_REVISION: Bundled clickhouse-c revision from clickhouse-c/UPSTREAM.

Traits§

AsyncTransport: Asynchronous byte stream used by AsyncClient.
Io: Byte transport used by clickhouse-c.

Functions§

cityhash128: Calculates CityHash128 and returns low and high words in wire order.

Type Aliases§

BoxedAsyncClient: AsyncClient with transport type erased.
Result: Result type used by this crate.