clickhouse_c/lib.rs
1//! Rust bindings for [clickhouse-c].
2//!
3//! Crate reads and writes ClickHouse Native blocks and implements native TCP
4//! protocol. API has three layers:
5//!
6//! 1. [`sys`] exposes unsafe C API.
7//! 2. [`BlockReader`], [`BlockBuilder`], [`Client`], and related types provide
8//! safe block and protocol operations.
9//! 3. [`PosixIo`], [`AsyncClient`], and [`tls`] provide transport adapters.
10//!
11//! # Entry points
12//!
13//! * Use [`BlockReader`] and [`BlockBuilder`] for Native block streams over
14//! any [`Io`] implementation.
15//! * Use [`Client`] for blocking native TCP protocol.
16//! * Use [`IolessClient`] to process protocol bytes with caller-managed I/O.
17//! * Enable `tokio` feature and use [`AsyncClient`] for asynchronous TCP.
18//! * Enable `tls` feature and use [`tls::TlsIo`] or
19//! [`AsyncClient::connect_tls`] for rustls connections.
20//!
21//! # Safety model
22//!
23//! Safe API depends on invariants documented by bundled clickhouse-c revision,
24//! available as [`UPSTREAM_REVISION`]. Slice lengths are bounded by owning C
25//! values.
26//!
27//! Decoding does not automatically validate relationships between nested
28//! columns. Call [`Block::validate`] before using offsets or dictionary keys
29//! from untrusted input as indexes.
30//!
31//! Types containing self-references, including [`PosixIo`], [`Codec`], and
32//! `tls::TlsIo`, return `Pin<Box<Self>>`. Owning handles implement `Send`.
33//! Connection handles do not implement `Sync`.
34//!
35//! [clickhouse-c]: https://github.com/ClickHouse/clickhouse-c
36
37// Keep C function signatures visible in FFI wrappers
38#![allow(clippy::too_many_arguments)]
39
40/// Bundled [clickhouse-c] revision from `clickhouse-c/UPSTREAM`.
41///
42/// [clickhouse-c]: https://github.com/ClickHouse/clickhouse-c
43pub const UPSTREAM_REVISION: &str = env!("CHC_UPSTREAM_REVISION");
44
45pub mod sys;
46
47mod alloc;
48#[cfg(feature = "tokio")]
49mod async_client;
50mod block;
51mod builder;
52mod client;
53mod codec;
54mod error;
55mod io;
56mod ioless;
57#[cfg(test)]
58mod parity;
59mod query;
60#[cfg(feature = "tls")]
61pub mod tls;
62mod types;
63
64pub use alloc::Allocator;
65#[cfg(feature = "tokio")]
66pub use async_client::{AsyncClient, AsyncTransport, BoxedAsyncClient};
67pub use block::{Block, BlockOpts, BlockReader, Column, ColumnLayout, LowCardinalityView};
68pub use builder::{BlockBuilder, ColumnBuilder};
69pub use client::{
70 Client, ClientOpts, Event, Exception, PacketKind, ProfileInfo, Progress, ServerInfo,
71};
72pub use codec::{Codec, Compression, cityhash128};
73pub use error::{Error, ErrorKind, Result};
74pub use io::{CancelToken, Io, PosixIo, SliceIo};
75pub use ioless::{IolessClient, Step};
76pub use query::{QueryOpts, QueryParam, QuerySetting};
77pub use types::{IntervalUnit, Kind, TypeAst, TypeRef};