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 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_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 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 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 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.