Struct Client 

pub struct Client { /* private fields */ }

A client containing HTTP pool.

Cloning behavior

Clones share the same HTTP transport but store their own configurations. Any with_* configuration method (e.g., Client::with_option) applies only to future clones, because Client::clone creates a deep copy of the Client configuration, except the transport.

Implementations

impl Client

pub async fn insert_data_row( &self, table: &str, proto: &DataRow, ) -> Result<DataRowInsert>

Available on crate feature sea-ql only.

Starts an INSERT for dynamically-typed DataRow values.

proto is used to determine column names; all rows passed to DataRowInsert::write_row must have values in the same column order.

When validation is enabled (the default), the table schema is fetched once and cached. This enables correct encoding of Nullable columns, Date/DateTime/UUID types, and schema mismatch detection.

When validation is disabled, a best-effort RowBinary encoding is used that works correctly only for non-nullable primitive columns.

impl Client

pub async fn insert_arrow( &self, table: &str, schema: &Schema, ) -> Result<DataRowInsert>

Available on crate feature arrow only.

Starts an INSERT for an Arrow [RecordBatch].

Column names are taken from the batch schema. All batches passed to DataRowInsert::write_batch must have a matching schema.

Internally builds a prototype DataRow from the schema and delegates to Client::insert_data_row, so validation and typed encoding apply in the same way.

impl Client

pub fn with_http_client(client: impl HttpClient) -> Self

Creates a new client with a specified underlying HTTP client.

See HttpClient for details.

pub fn with_url(self, url: impl Into<String>) -> Self

Specifies ClickHouse’s url. Should point to HTTP endpoint.

Automatically clears the metadata cache for this instance only.

Examples

let client = Client::default().with_url("http://localhost:8123");

pub fn with_database(self, database: impl Into<String>) -> Self

Specifies a database name.

Automatically clears the metadata cache for this instance only.

Examples

let client = Client::default().with_database("test");

pub fn with_user(self, user: impl Into<String>) -> Self

Specifies a user.

Panics

If called after Client::with_access_token.

Examples

let client = Client::default().with_user("test");

pub fn with_password(self, password: impl Into<String>) -> Self

Specifies a password.

Panics

If called after Client::with_access_token.

Examples

let client = Client::default().with_password("secret");

pub fn with_roles( self, roles: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Configure the roles to use when executing statements with this Client instance.

Overrides any roles previously set by this method or Client::with_option.

Call Client::with_default_roles to clear any explicitly set roles.

This setting is copied into cloned clients.

Examples

// Single role
let client = Client::default().with_roles(["foo"]);

// Multiple roles
let client = Client::default().with_roles(["foo", "bar", "baz"]);

pub fn with_default_roles(self) -> Self

Clear any explicitly set roles from this Client instance.

Overrides any roles previously set by Client::with_roles or Client::with_option.

pub fn with_access_token(self, access_token: impl Into<String>) -> Self

A JWT access token to authenticate with ClickHouse. JWT token authentication is supported in ClickHouse Cloud only. Should not be called after Client::with_user or Client::with_password.

Panics

If called after Client::with_user or Client::with_password.

Examples

let client = Client::default().with_access_token("jwt");

pub fn with_compression(self, compression: Compression) -> Self

Specifies a compression mode. See Compression for details. By default, Lz4 is used.

Examples

let client = Client::default().with_compression(Compression::Lz4);

pub fn with_option( self, name: impl Into<String>, value: impl Into<String>, ) -> Self

Used to specify options that will be passed to all queries.

Example

Client::default().with_option("allow_nondeterministic_mutations", "1");

pub fn with_header( self, name: impl Into<String>, value: impl Into<String>, ) -> Self

Used to specify a header that will be passed to all queries.

Example

Client::default().with_header("Cookie", "A=1");

pub fn with_product_info( self, product_name: impl Into<String>, product_version: impl Into<String>, ) -> Self

Specifies the product name and version that will be included in the default User-Agent header. Multiple products are supported. This could be useful for the applications built on top of this client.

Examples

Sample default User-Agent header:

clickhouse-rs/0.12.2 (lv:rust/1.67.0, os:macos)

Sample User-Agent with a single product information:

let client = Client::default().with_product_info("MyDataSource", "v1.0.0");

MyDataSource/v1.0.0 clickhouse-rs/0.12.2 (lv:rust/1.67.0, os:macos)

Sample User-Agent with multiple products information (NB: the products are added in the reverse order of Client::with_product_info calls, which could be useful to add higher abstraction layers first):

let client = Client::default()
    .with_product_info("MyDataSource", "v1.0.0")
    .with_product_info("MyApp", "0.0.1");

MyApp/0.0.1 MyDataSource/v1.0.0 clickhouse-rs/0.12.2 (lv:rust/1.67.0, os:macos)

pub fn set_option( &mut self, name: impl Into<String>, value: impl Into<String>, ) -> Option<String>

Set an option on this instance of Client.

Returns the previous value for the option, if one was set.

pub fn get_option(&self, name: impl AsRef<str>) -> Option<&str>

Get an option that was previously set on this Client.

pub async fn insert<T: Row>(&self, table: &str) -> Result<Insert<T>>

Starts a new INSERT statement.

Validation

If validation is enabled (default), RowBinaryWithNamesAndTypes input format is used. When Client::insert method is called for this table for the first time, it will fetch the table schema from the server, allowing to validate the serialized rows, as well as write the names and types of the columns in the request header.

Fetching the schema will happen only once per table, as the schema is cached by the client internally.

With disabled validation, the schema is not fetched, and the rows serialized with RowBinary input format.

Panics

If T has unnamed fields, e.g. tuples.

pub async fn insert_any<T: Row>(&self, table: &str) -> Result<Insert<()>>

Creates a type-erased [Insert<()>] for table, using T to derive column names and (when validation is enabled) to fetch and cache row metadata.

This lets you to store Insert<()> in a container, for example HashMap<std::any::TypeId, Insert<()>>.

let mut insert = client.insert_any::<MyRow>("table").await?;
insert.write_any(&MyRow { ... }).await?;
insert.end().await?;

pub fn inserter<T: Row>(&self, table: &str) -> Inserter<T>

Available on crate feature inserter only.

Creates an inserter to perform multiple INSERT statements.

pub fn insert_formatted_with(&self, sql: impl Into<String>) -> InsertFormatted

Start an INSERT statement sending pre-formatted data.

sql should be an INSERT INTO ... FORMAT <format name> statement. Any other type of statement may produce incorrect results.

The statement is not issued until the first call to .send().

Note: Not Validated

Unlike Insert and Inserter, this does not perform any validation on the submitted data.

Only the use of self-describing formats (e.g. CSV, TabSeparated, JSON) is recommended.

See the list of supported formats for details.

pub fn query(&self, query: &str) -> Query

Starts a new SELECT/DDL query.

pub fn with_validation(self, enabled: bool) -> Self

Enables or disables Row data types validation against the database schema at the cost of performance. Validation is enabled by default, and in this mode, the client will use RowBinaryWithNamesAndTypes format.

If you are looking to maximize performance, you could disable validation using this method. When validation is disabled, the client switches to RowBinary format usage instead.

The downside with plain RowBinary is that instead of clearer error messages, a mismatch between Row and database schema will result in a error::Error::NotEnoughData error without specific details.

However, depending on the dataset, there might be x1.1 to x3 performance improvement, but that highly depends on the shape and volume of the dataset.

It is always recommended to measure the performance impact of validation in your specific use case. Additionally, writing smoke tests to ensure that the row types match the ClickHouse schema is highly recommended, if you plan to disable validation in your application.

Note: Mocking

When using test::Mock with the test-util feature, validation is forced off.

This applies either when using Client::with_mock(), or Client::with_url() with a URL from test::Mock::url().

As of writing, the mocking facilities are unable to generate the RowBinaryWithNamesAndTypes header required for validation to function.

pub async fn clear_cached_metadata(&self)

Clear table metadata that was previously received and cached.

Insert uses cached metadata when sending data with validation. If the table schema changes, this metadata needs to re-fetched.

This method clears the metadata cache, causing future insert queries to re-fetch metadata. This applies to all cloned instances of this Client (using the same URL and database) as well.

This may need to wait to acquire a lock if a query is concurrently writing into the cache.

Cancel-safe.

pub fn with_mock(self, mock: &Mock) -> Self

Available on crate feature test-util only.

Use a mock server for testing purposes.

Note

The client will always use RowBinary format instead of RowBinaryWithNamesAndTypes, as otherwise it’d be required to provide RBWNAT header in the mocks, which is pointless in that kind of tests.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Client

fn default() -> Self

Returns the “default value” for a type.