Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

Builder for constructing a Client with custom connection options.

Implementations

impl ClientBuilder

pub fn new() -> Self

Create a new builder with default options.

pub fn host(self, host: &str, port: u16) -> Self

Add a server address (host and port).

pub fn url(self, url: &str) -> Result<Self>

Add a server by URL, extracting host, port, TLS, and auth settings.

pub fn cluster(self) -> Self

Enable cluster mode.

pub fn tls(self) -> Self

Enable TLS with certificate verification.

pub fn tls_insecure(self) -> Self

Enable TLS without certificate verification.

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

Set the authentication password.

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

Set the authentication username (ACL).

pub fn database(self, db: i64) -> Self

Select the database number.

pub fn read_from(self, strategy: ReadFrom) -> Self

Set the read-from strategy (primary, replica, etc.).

pub fn connect_timeout(self, timeout: Duration) -> Self

Set the connection timeout.

pub fn request_timeout(self, timeout: Duration) -> Self

Set the per-request timeout.

pub fn blocking_cmd_timeout_extension(self, extension: Duration) -> Self

Extra time added to a blocking command’s server-side timeout when computing the client-side request deadline.

Blocking commands (BLPOP, BLMPOP, XREAD BLOCK, etc.) pass a server-side timeout as part of the command payload. To prevent the client from failing a request that the server is legitimately about to answer, the client waits server_timeout + extension before treating the command as timed out. The extension is a safety margin over slow links or loaded servers.

Defaults to 500ms. Under concurrent blocking pressure (many clients waking at the same server timeout), 500ms can be insufficient — consider 1s or 2s if you observe late responders losing their replies.

pub fn max_inflight(self, max_inflight: u32) -> Self

Set the maximum number of in-flight requests.

pub fn retry_strategy(self, strategy: ConnectionRetryStrategy) -> Self

Set the connection retry strategy.

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

Set the client name sent to the server.

pub fn protocol(self, proto: ProtocolVersion) -> Self

Set the RESP protocol version.

pub fn lazy_connect(self) -> Self

👎Deprecated since 0.1.1:

Use ClientBuilder::build_lazy() -> LazyClient instead. lazy_connect() sets a flag that Client::new now rejects; the connect-on-first-use path lives on LazyClient.

Enable lazy connection (connect on first command, not on build).

Deprecated. The lazy_connect flag on ConnectionRequest no longer alters Client::new / build() behaviour — those entry points always return a connected Client or an error. The connect-on-first-use path moved to a dedicated type: construct a LazyClient via ClientBuilder::build_lazy or LazyClient::from_config.

Callers still chaining .lazy_connect().build() will see build() return InvalidClientConfig at runtime — the deprecation warning here surfaces the migration at compile time.

pub fn tcp_nodelay(self) -> Self

Enable TCP_NODELAY.

pub fn pubsub_subscriptions(self, subs: PubSubSubscriptionInfo) -> Self

Set PubSub subscriptions for the connection.

pub fn push_sender(self, tx: UnboundedSender<PushInfo>) -> Self

Receive RESP3 push frames (pub/sub messages, invalidation notices, keyspace notifications) on a caller-provided channel.

The sender half is wired into every connection this client owns; push frames that the connection receives are forwarded to it verbatim as crate::PushInfo values.

Push delivery requires RESP3 — build the client with ClientBuilder::protocol set to crate::value::ProtocolVersion::RESP3. Subscribing to channels is performed separately via:

• build-time: ClientBuilder::pubsub_subscriptions (replayed on reconnect);
• runtime: client.cmd("SUBSCRIBE").arg("chan").execute::<()>().await? (intercepted by the pubsub synchronizer and reconciled in the background; the call returns as soon as the desired state is recorded).

Example

let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
let client = ClientBuilder::new()
    .host("127.0.0.1", 6379)
    .protocol(ProtocolVersion::RESP3)
    .push_sender(tx)
    .build()
    .await?;

// Request a subscription. The reconciler issues SUBSCRIBE in the
// background; push frames arrive on `rx` once the server confirms.
let _: () = client.cmd("SUBSCRIBE").arg("events").execute().await?;
while let Some(push) = rx.recv().await {
    // handle push frame
    let _ = push;
}

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

Build and connect the client.

pub fn build_lazy(self) -> Result<LazyClient>

Build a client that defers TCP connection until the first command is executed.

Unlike build, this does NOT attempt to reach the server — it validates the address list and returns a LazyClient synchronously. The underlying connection is established on the first LazyClient::connect call (or implicitly on the first command issued through the returned &Client). Subsequent calls reuse the already- established connection; a OnceCell guarantees connect runs exactly once.

Use this when you want a client handle you can construct synchronously and thread through app startup, but where the Valkey endpoint may not be reachable yet (e.g. the server is part of the same deployment and comes up later).

Trait Implementations

impl Default for ClientBuilder

fn default() -> Self

Returns the “default value” for a type.