clickhouse_native_client/
lib.rs

1//! # ClickHouse Native Client
2//!
3//! A native async Rust client for ClickHouse database, ported from the C++
4//! [clickhouse-cpp](https://github.com/ClickHouse/clickhouse-cpp) library.
5//!
6//! This crate implements the ClickHouse native TCP binary protocol with
7//! LZ4/ZSTD compression, TLS support, and all major ClickHouse data types.
8//!
9//! # Production Readiness
10//!
11//! Most of the codebase was created by converting the C++ clickhouse-cpp
12//! client. Although the client is already used to ingest TiBs of data a day
13//! and is relatively well covered by unit tests, there may be bugs. Test your
14//! use case before committing.
15//!
16//! # Quick Start
17//!
18//! ```no_run
19//! use clickhouse_native_client::{Client, ClientOptions, Block};
20//! use clickhouse_native_client::column::numeric::ColumnUInt64;
21//! use std::sync::Arc;
22//!
23//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
24//! // Connect to ClickHouse
25//! let opts = ClientOptions::new("localhost", 9000)
26//!     .database("default")
27//!     .user("default");
28//! let mut client = Client::connect(opts).await?;
29//!
30//! // Execute DDL
31//! client.execute("CREATE TABLE IF NOT EXISTS test (id UInt64) ENGINE = Memory").await?;
32//!
33//! // Insert data
34//! let mut col = ColumnUInt64::new();
35//! col.append(1);
36//! col.append(2);
37//! let mut block = Block::new();
38//! block.append_column("id", Arc::new(col))?;
39//! client.insert("test", block).await?;
40//!
41//! // Query data
42//! let result = client.query("SELECT id FROM test").await?;
43//! for block in result.blocks() {
44//!     println!("rows: {}", block.row_count());
45//! }
46//! # Ok(())
47//! # }
48//! ```
49//!
50//! # Feature Flags
51//!
52//! - **`tls`** - Enables TLS/SSL connections via `rustls` and `tokio-rustls`.
53//!
54//! # Modules
55//!
56//! - [`client`] - Async client API (`Client`, `ClientOptions`)
57//! - [`block`] - Data blocks (`Block`, `BlockInfo`)
58//! - [`mod@column`] - Column types for all ClickHouse data types
59//! - [`query`] - Query builder and protocol messages
60//! - [`types`] - ClickHouse type system and parser
61//! - [`compression`] - LZ4/ZSTD compression
62//! - [`protocol`] - Protocol constants (packet types, revisions)
63//! - [`error`] - Error types and `Result` alias
64//! - [`connection`] - Async TCP/TLS connection wrapper
65//! - [`wire_format`] - Wire protocol encoding helpers
66//! - [`io`] - Block reader/writer for async I/O
67//! - `ssl` - TLS/SSL options (requires `tls` feature)
68
69#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
70#![warn(missing_docs)]
71/// Data blocks (collections of named columns).
72pub mod block;
73/// Async client API and connection options.
74pub mod client;
75/// Column type implementations for all ClickHouse data types.
76pub mod column;
77/// LZ4 and ZSTD block compression.
78pub mod compression;
79/// Async TCP/TLS connection wrapper.
80pub mod connection;
81/// Error types and `Result` alias.
82pub mod error;
83/// Block reader/writer for async I/O.
84pub mod io;
85/// Protocol constants (packet types, revision numbers).
86pub mod protocol;
87/// Query builder and protocol messages.
88pub mod query;
89/// Re-exports from the connection module.
90pub mod socket;
91/// ClickHouse type system and type string parser.
92pub mod types;
93/// Wire protocol encoding helpers (varint, fixed-size types).
94pub mod wire_format;
95
96/// TLS/SSL connection options (requires the `tls` feature).
97#[cfg(feature = "tls")]
98pub mod ssl;
99
100pub use block::{
101    Block,
102    BlockInfo,
103};
104pub use client::{
105    Client,
106    ClientOptions,
107    Endpoint,
108    QueryResult,
109};
110pub use connection::ConnectionOptions;
111pub use error::{
112    Error,
113    Result,
114};
115pub use query::{
116    DataCallback,
117    DataCancelableCallback,
118    Exception,
119    ExceptionCallback,
120    ExternalTable,
121    Profile,
122    ProfileCallback,
123    ProfileEventsCallback,
124    Progress,
125    ProgressCallback,
126    Query,
127    QuerySettingsField,
128    ServerLogCallback,
129    TracingContext,
130};
131
132#[cfg(feature = "tls")]
133pub use ssl::SSLOptions;
clickhouse_native_client/lib.rs

clickhouse_native_client/
lib.rs
