Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

A builder for configuring and creating a ClickHouse client.

The ClientBuilder provides a fluent interface to set up a Client with custom connection parameters, such as the server address, credentials, TLS, compression, and session settings. It supports creating either a single Client (via ClientBuilder::build) or a connection pool (via ClientBuilder::build_pool_manager, with the pool feature enabled).

Use this builder for fine-grained control over the client configuration. The builder ensures that the destination address is verified before establishing a connection, either explicitly via ClientBuilder::verify or implicitly during the build process.

Examples

use clickhouse_arrow::prelude::*;

let client = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_username("default")
    .with_password("")
    .build_arrow()
    .await
    .unwrap();

// Use the client to query `ClickHouse`
client.query("SELECT 1").await.unwrap();

Implementations

impl ClientBuilder

pub fn new() -> Self

Creates a new ClientBuilder with default configuration.

This method initializes a builder with default ClientOptions, no destination, settings, or context. Use this as the starting point to configure a ClickHouse client with methods like ClientBuilder::with_endpoint, ClientBuilder::with_username, or ClientBuilder::with_tls.

Returns

A new ClientBuilder instance ready for configuration.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_username("default");

pub fn destination(&self) -> Option<&Destination>

Retrieves the configured destination, if set.

This method returns the ClickHouse server address (as a Destination) that has been configured via methods like ClientBuilder::with_endpoint or ClientBuilder::with_socket_addr. Returns None if no destination is set.

Returns

An Option<&Destination> containing the configured destination, or None if not set.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000");
if let Some(dest) = builder.destination() {
    println!("Destination: {:?}", dest);
}

pub fn options(&self) -> &ClientOptions

Retrieves the current connection options.

This method returns a reference to the ClientOptions configured for the builder, which includes settings like username, password, TLS, and compression. These options can be set via methods like ClientBuilder::with_username, ClientBuilder::with_tls, or ClientBuilder::with_options.

Returns

A reference to the current ClientOptions.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_username("default")
    .with_endpoint("localhost:9000");
let options = builder.options();
println!("Username: {}", options.username);

pub fn settings(&self) -> Option<&Settings>

Retrieves the configured session settings, if set.

This method returns the ClickHouse session settings (as Settings) that have been configured via ClientBuilder::with_settings. These settings control query behavior, such as timeouts or maximum rows. Returns None if no settings are set.

Returns

An Option<&Settings> containing the configured settings, or None if not set.

Examples

use clickhouse_arrow::prelude::*;
use std::sync::Arc;

let settings = Settings::default();
let builder = ClientBuilder::new()
    .with_settings(settings.clone());
if let Some(config_settings) = builder.settings() {
    println!("Settings: {config_settings:?}");
    assert_eq!(config_settings, &settings)
}

pub fn verified(&self) -> bool

Checks whether the builder’s destination has been verified.

A verified builder indicates that the ClickHouse server’s destination address has been resolved into valid socket addresses (via ClientBuilder::verify or during ClientBuilder::build). Verification ensures that the address is reachable before attempting to connect. This method returns false if the destination is unset or has been modified since the last verification.

Returns

A bool indicating whether the destination is verified.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000");
println!("Verified: {}", builder.verified()); // false

let verified_builder = builder.verify().await.unwrap();
println!("Verified: {}", verified_builder.verified()); // true

pub fn with_socket_addr(self, addr: SocketAddr) -> Self

Sets the ClickHouse server address using a socket address.

This method configures the destination using a SocketAddr (e.g., 127.0.0.1:9000). It is useful when the address is already resolved. For hostname-based addresses, use ClientBuilder::with_endpoint or ClientBuilder::with_host_port.

Parameters

• addr: The socket address of the ClickHouse server.

Returns

A new ClientBuilder with the updated destination.

Examples

use clickhouse_arrow::prelude::*;
use std::net::{Ipv4Addr, SocketAddr};

let addr = SocketAddr::new(Ipv4Addr::new(127, 0, 0, 1).into(), 9000);
let builder = ClientBuilder::new()
    .with_socket_addr(addr);

pub fn with_host_port(self, host: impl Into<String>, port: u16) -> Self

Sets the ClickHouse server address using a hostname and port.

This method configures the destination using a hostname (e.g., "localhost") and port number (e.g., 9000). The hostname will be resolved during verification (via ClientBuilder::verify or ClientBuilder::build). For resolved addresses, use ClientBuilder::with_socket_addr.

Parameters

• host: The hostname or IP address of the ClickHouse server.
• port: The port number of the ClickHouse server.

Returns

A new ClientBuilder with the updated destination.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_host_port("localhost", 9000);

pub fn with_endpoint(self, endpoint: impl Into<String>) -> Self

Sets the ClickHouse server address using a string endpoint.

This method configures the destination using a string in the format "host:port" (e.g., "localhost:9000"). The endpoint will be resolved during verification (via ClientBuilder::verify or ClientBuilder::build). For separate host and port, use ClientBuilder::with_host_port.

Parameters

• endpoint: The ClickHouse server address as a string (e.g., "localhost:9000").

Returns

A new ClientBuilder with the updated destination.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000");

pub fn with_destination<D>(self, destination: D) -> Self

where D: Into<Destination>,

Sets the ClickHouse server address using any compatible destination type.

This method configures the destination using a type that can be converted into a Destination, such as a string endpoint (e.g., "localhost:9000"), a (host, port) tuple, or a SocketAddr. It is the most flexible way to set the destination. For specific formats, use ClientBuilder::with_endpoint, ClientBuilder::with_host_port, or ClientBuilder::with_socket_addr.

Parameters

• destination: The ClickHouse server address, convertible to Destination.

Returns

A new ClientBuilder with the updated destination.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_destination("localhost:9000");

pub fn with_options(self, options: ClientOptions) -> Self

Sets the connection options directly.

This method replaces the current ClientOptions with the provided options, overriding any settings configured via methods like ClientBuilder::with_username or ClientBuilder::with_tls. Use this when you have a pre-configured ClientOptions instance or need to set multiple options at once.

Parameters

• options: The ClientOptions to use for the connection.

Returns

A new ClientBuilder with the updated options.

Examples

use clickhouse_arrow::prelude::*;

let options = ClientOptions::default()
    .username("default")
    .password("");
let builder = ClientBuilder::new()
    .with_options(options);

pub fn with_ext<F>(self, cb: F) -> Self

where F: FnOnce(Extension) -> Extension,

pub fn with_tls(self, tls: bool) -> Self

Enables or disables TLS for the ClickHouse connection.

This method configures whether the client will use a secure TLS connection to communicate with ClickHouse. If TLS is enabled, you may also need to set a CA file (via ClientBuilder::with_cafile) or domain (via ClientBuilder::with_domain) for secure connections.

Parameters

• tls: If true, enables TLS; if false, uses plain TCP.

Returns

A new ClientBuilder with the updated TLS setting.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_tls(true);

pub fn with_cafile<P: AsRef<Path>>(self, cafile: P) -> Self

Sets the CA file for TLS connections to ClickHouse.

This method specifies the path to a certificate authority (CA) file used to verify the ClickHouse server’s certificate during TLS connections. It is required when TLS is enabled (via ClientBuilder::with_tls) and the server uses a custom or self-signed certificate.

Parameters

• cafile: The path to the CA file.

Returns

A new ClientBuilder with the updated CA file setting.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_tls(true)
    .with_cafile("/path/to/ca.crt");

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

Forces the use of IPv4-only resolution for the ClickHouse server address.

This method configures whether the destination address resolution (during ClientBuilder::verify or ClientBuilder::build) should use only IPv4 addresses. By default, both IPv4 and IPv6 are considered. Enable this for environments where IPv6 is unsupported.

Parameters

• enabled: If true, restricts resolution to IPv4; if false, allows both IPv4 and IPv6.

Returns

A new ClientBuilder with the updated IPv4 setting.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_ipv4_only(true);

pub fn with_settings(self, settings: impl Into<Settings>) -> Self

Sets the ClickHouse session settings.

This method configures the session settings (e.g., query timeouts, max rows) for the client. These settings are applied to all queries executed by the client. Use this to customize query behavior beyond the defaults.

Parameters

• settings: The session settings as an impl Into<Settings>.

Returns

A new ClientBuilder with the updated settings.

Examples

use clickhouse_arrow::prelude::*;
use std::sync::Arc;

let settings = vec![
    ("select_sequential_consistency", 1)
];
let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_settings(settings);

pub fn with_setting( self, name: impl Into<String>, setting: impl Into<SettingValue>, ) -> Self

Set a ClickHouse session setting.

This method configures the session settings (e.g., query timeouts, max rows) for the client. These settings are applied to all queries executed by the client. Use this to customize query behavior beyond the defaults.

Parameters

• key: The session setting’s name.
• setting: The session setting as an impl Into<SettingValue>.

Returns

A new ClientBuilder with the updated settings.

Examples

use clickhouse_arrow::prelude::*;
use std::sync::Arc;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_setting("select_sequential_consistency", 1);

pub fn with_username(self, username: impl Into<String>) -> Self

Sets the username for authenticating with ClickHouse.

This method configures the username used to authenticate the client with the ClickHouse server. The default username is typically "default", but this can be customized based on the server’s configuration.

Parameters

• username: The username for authentication.

Returns

A new ClientBuilder with the updated username.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_username("admin");

pub fn with_password<T>(self, password: T) -> Self

where Secret: From<T>,

Sets the password for authenticating with ClickHouse.

This method configures the password used to authenticate the client with the ClickHouse server. The password is stored securely as a Secret. If no password is required, an empty string can be used.

Parameters

• password: The password for authentication, convertible to Secret.

Returns

A new ClientBuilder with the updated password.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_username("admin")
    .with_password("secret");

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

Sets the default database for the ClickHouse connection.

This method configures the default database used by the client for queries and operations. If not set, the ClickHouse server defaults to the "default" database. Specifying a database is optional but recommended when working with a specific database to avoid explicit database prefixes in queries.

Parameters

• database: The name of the default database.

Returns

A new ClientBuilder with the updated database.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_database("my_db");

pub fn with_domain(self, domain: impl Into<String>) -> Self

Sets the domain for secure TLS connections to ClickHouse.

This method specifies the domain name used for TLS verification when connecting to a ClickHouse server with TLS enabled (via ClientBuilder::with_tls). If not set, the domain is inferred from the destination during verification. Use this to explicitly set the domain for cloud or custom TLS configurations.

Parameters

• domain: The domain name for TLS verification.

Returns

A new ClientBuilder with the updated domain.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_tls(true)
    .with_domain("clickhouse.example.com");

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

Sets the compression method for data exchange with ClickHouse.

This method configures the compression algorithm used for sending and receiving data to/from ClickHouse. The default is CompressionMethod::LZ4, which balances performance and compression ratio. Other options may be available depending on the ClickHouse server configuration.

Parameters

• compression: The compression method to use.

Returns

A new ClientBuilder with the updated compression setting.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_compression(CompressionMethod::LZ4);

pub fn with_arrow_options(self, options: ArrowOptions) -> Self

Sets the Arrow-specific options for ClickHouse connections.

This method configures options specific to the Arrow format (used by Client<ArrowFormat>), such as schema mapping or data type conversions. These options are applied when the client is built with ClientBuilder::build for ArrowFormat. Use this to customize Arrow interoperability.

Parameters

• options: The Arrow-specific options.

Returns

A new ClientBuilder with the updated Arrow options.

Examples

use clickhouse_arrow::prelude::*;

let arrow_options = ArrowOptions::default();
let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_arrow_options(arrow_options);

pub fn with_trace_context(self, trace_context: TraceContext) -> Self

Sets a tracing context for ClickHouse connections and queries.

This method configures a TraceContext to enable distributed tracing for client operations, such as connections and queries. The tracing context is included in logs and can be used to monitor and debug client behavior across distributed systems.

Parameters

• trace_context: The tracing context to use.

Returns

A new ClientBuilder with the updated tracing context.

Examples

use clickhouse_arrow::prelude::*;

let trace_context = TraceContext::default();
let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_trace_context(trace_context);

pub async fn verify(self) -> Result<Self>

Resolves and verifies the ClickHouse server destination early.

This method resolves the configured destination (set via ClientBuilder::with_endpoint, etc.) into socket addresses and verifies that it is valid and reachable. It also ensures that a domain is set for TLS connections if required. Verification is performed automatically during ClientBuilder::build, but calling this method explicitly allows early error detection.

Returns

A Result containing the verified ClientBuilder, or an error if verification fails.

Errors

• Fails if no destination is set (Error::MissingConnectionInformation).
• Fails if the destination cannot be resolved (Error::MalformedConnectionInformation).
• Fails if TLS is enabled but no domain is provided and cannot be inferred (Error::MalformedConnectionInformation).

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000");
let verified_builder = builder.verify().await.unwrap();
println!("Destination verified!");

pub async fn build<T: ClientFormat>(self) -> Result<Client<T>>

Builds a ClickHouse client by connecting to the configured destination.

This method creates a Client using the configured destination, options, settings, and context. It verifies the destination (via ClientBuilder::verify if not already verified) and establishes a connection to the ClickHouse server. The client type (NativeClient or Client<ArrowFormat>) is determined by the format T (e.g., NativeFormat or ArrowFormat).

Parameters

• T: The client format, either NativeFormat or ArrowFormat.

Returns

A Result containing the connected Client<T>, or an error if the connection fails.

Errors

• Fails if the destination is unset or invalid (Error::MissingConnectionInformation, Error::MalformedConnectionInformation).
• Fails if the connection cannot be established (e.g., network issues, authentication failure).
• Fails if TLS or cloud-specific configurations are invalid.

Panics

• Shouldn’t panic, verification guarantees destination.

Examples

use clickhouse_arrow::prelude::*;

let client = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_username("default")
    .build_arrow()
    .await
    .unwrap();
client.query("SELECT 1").await.unwrap();

pub async fn build_arrow(self) -> Result<Client<ArrowFormat>>

A helper method to build a Client<ArrowFormat> directly

Errors

• Returns an error if destination verification fails.

Panics

• Shouldn’t panic, verification guarantees destination.

pub async fn build_native(self) -> Result<Client<NativeFormat>>

A helper method to build a Client<NativeFormat> directly

Errors

• Returns an error if destination verification fails.

Panics

• Shouldn’t panic, verification guarantees destination.

pub async fn build_pool_manager<T: ClientFormat>( self, check_health: bool, ) -> Result<ConnectionManager<T>>

Builds a connection pool manager for ClickHouse clients.

This method creates a ConnectionManager<T> for managing a pool of Client<T> instances, allowing efficient reuse of connections. It verifies the destination and configures the manager with the specified health check behavior. The client type (NativeClient or Client<ArrowFormat>) is determined by the format T (e.g., NativeFormat or ArrowFormat).

Parameters

• check_health: If true, the manager performs health checks on connections before reusing them.

Returns

A Result containing the ConnectionManager<T>, or an error if verification or setup fails.

Errors

• Fails if the destination is unset or invalid (Error::MissingConnectionInformation, Error::MalformedConnectionInformation).
• Fails if the manager cannot be initialized (e.g., invalid configuration).

Feature

Requires the pool feature to be enabled.

Examples

use clickhouse_arrow::prelude::*;

let manager = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_username("default")
    .build_pool_manager::<ArrowFormat>(true)
    .await
    .unwrap();
// Use the manager to get a client from the pool
let client = manager.get().await.unwrap();
client.query("SELECT 1").await.unwrap();

impl ClientBuilder

pub fn connection_identifier(&self) -> String

Generates a unique identifier for the connection configuration.

This method creates a string identifier based on the destination, username, password, database, and domain configured in the builder. It is useful for distinguishing between different connection configurations, especially when managing multiple clients or pools. The identifier includes a hashed password for security.

Returns

A String representing the connection configuration.

Examples

use clickhouse_arrow::prelude::*;

let builder = ClientBuilder::new()
    .with_endpoint("localhost:9000")
    .with_username("default")
    .with_password("secret");
let id = builder.connection_identifier();
println!("Connection ID: {}", id);

Trait Implementations

impl Clone for ClientBuilder

fn clone(&self) -> ClientBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ClientBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ClientBuilder

fn default() -> ClientBuilder

Returns the “default value” for a type.