Skip to content

Home / node / BaseClient / interfaces / BaseClientConfiguration @valkey/valkey-glide

@valkey/valkey-glide / BaseClient / BaseClientConfiguration

Interface: BaseClientConfiguration

Configuration settings for creating a client. Shared settings for standalone and cluster clients.

Remarks

The BaseClientConfiguration interface defines the foundational configuration options used when creating a client to connect to a Valkey server or cluster. It includes connection details, authentication, communication protocols, and various settings that influence the client's behavior and interaction with the server.

Connection Details

  • Addresses: Use the addresses property to specify the hostnames and ports of the server(s) to connect to.
  • Cluster Mode: In cluster mode, the client will discover other nodes based on the provided addresses.
  • Standalone Mode: In standalone mode, only the provided nodes will be used.
  • Lazy Connect: Set lazyConnect to true to defer connection establishment until the first command is sent.

Security Settings

  • TLS: Enable secure communication using useTLS. Should match the TLS configuration of the server/cluster, otherwise the connection attempt will fail. For advanced tls configuration, , see AdvancedBaseClientConfiguration.
  • Authentication: Provide credentials to authenticate with the server.

Communication Settings

  • Request Timeout: Set requestTimeout to specify how long the client should wait for a request to complete.
  • Protocol Version: Choose the serialization protocol using protocol.

Client Identification

  • Client Name: Set clientName to identify the client connection.

Read Strategy

  • Use readFrom to specify the client's read strategy (e.g., primary, preferReplica, AZAffinity, AZAffinityReplicasAndPrimary).

Availability Zone

  • Use clientAz to specify the client's availability zone, which can influence read operations when using readFrom: 'AZAffinity'orreadFrom: 'AZAffinityReplicasAndPrimary'`.

Decoder Settings

  • Default Decoder: Set defaultDecoder to specify how responses are decoded by default.

Concurrency Control

  • Inflight Requests Limit: Control the number of concurrent requests using inflightRequestsLimit.

Reconnection Strategy

  • Reconnection Strategy: Customize how the client should attempt reconnections using connectionBackoff.
  • numberOfRetries: The maximum number of retry attempts with increasing delays.
    • After this limit is reached, the retry interval becomes constant.
  • factor: A multiplier applied to the base delay between retries (e.g., 500 means a 500ms base delay).
  • exponentBase: The exponential growth factor for delays (e.g., 2 means the delay doubles with each retry).
  • jitterPercent: An optional percentage of jitter to add to the delay (e.g., 30 means the final delay will vary randomly between 70% and 130% of the calculated delay).

Example

const config: BaseClientConfiguration = {
  addresses: [
    { host: 'redis-node-1.example.com', port: 6379 },
    { host: 'redis-node-2.example.com' }, // Defaults to port 6379
  ],
  useTLS: true,
  credentials: {
    username: 'myUser',
    password: 'myPassword',
  },
  requestTimeout: 5000, // 5 seconds
  protocol: ProtocolVersion.RESP3,
  clientName: 'myValkeyClient',
  readFrom: ReadFrom.AZAffinity,
  clientAz: 'us-east-1a',
  defaultDecoder: Decoder.String,
  inflightRequestsLimit: 1000,
  connectionBackoff: {
    numberOfRetries: 10, // Maximum retries before delay becomes constant
    factor: 500,        // Base delay in milliseconds
    exponentBase: 2,    // Delay doubles with each retry (2^N)
    jitterPercent: 20,   // Optional jitter percentage
  },
  lazyConnect: true,
};

Properties

addresses

addresses: object[]

DNS Addresses and ports of known nodes in the cluster. If the server is in cluster mode the list can be partial, as the client will attempt to map out the cluster and find all nodes. If the server is in standalone mode, only nodes whose addresses were provided will be used by the client.

host

host: string

port?

optional port: number

If port isn't supplied, 6379 will be used

Example

configuration.addresses =
[
  { address: sample-address-0001.use1.cache.amazonaws.com, port:6378 },
  { address: sample-address-0002.use2.cache.amazonaws.com }
  { address: sample-address-0003.use2.cache.amazonaws.com, port:6380 }
]

clientAz?

optional clientAz: string

Availability Zone of the client. If ReadFrom strategy is AZAffinity or AZAffinityReplicasAndPrimary, this setting ensures that readonly commands are directed to nodes within the specified AZ if they exist.

Example

// Example configuration for setting client availability zone and read strategy
configuration.clientAz = 'us-east-1a'; // Sets the client's availability zone
configuration.readFrom = 'AZAffinity'; // Directs read operations to nodes within the same AZ
Or
configuration.readFrom = 'AZAffinityReplicasAndPrimary'; // Directs read operations to any node (primary or replica) within the same AZ

clientName?

optional clientName: string

Client name to be used for the client. Will be used with CLIENT SETNAME command during connection establishment.

connectionBackoff?

optional connectionBackoff: object

Strategy used to determine how and when to reconnect, in case of connection failures. The time between attempts grows exponentially, following the formula rand(0 ... factor * (exponentBase ^ N)), where N is the number of failed attempts, and rand(...) applies a jitter of up to jitterPercent% to introduce randomness and reduce retry storms. The client will attempt to reconnect indefinitely. Once the maximum value is reached, that will remain the time between retry attempts until a reconnect attempt is successful. If not set, a default backoff strategy will be used.

exponentBase

exponentBase: number

The exponent base configured for the strategy. Value must be an integer.

factor

factor: number

The multiplier that will be applied to the waiting time between each retry. Value must be an integer.

jitterPercent?

optional jitterPercent: number

The Jitter percent on the calculated duration. If not set, a default value will be used. Value is optional, and must be an integer.

numberOfRetries

numberOfRetries: number

Number of retry attempts that the client should perform when disconnected from the server, where the time between retries increases. Once the retries have reached the maximum value, the time between retries will remain constant until a reconnect attempt is succesful. Value must be an integer.

credentials?

optional credentials: ServerCredentials

Credentials for authentication process. If none are set, the client will not authenticate itself with the server.

defaultDecoder?

optional defaultDecoder: Decoder

Default decoder when decoder is not set per command. If not set, 'Decoder.String' will be used.

inflightRequestsLimit?

optional inflightRequestsLimit: number

The maximum number of concurrent requests allowed to be in-flight (sent but not yet completed). This limit is used to control the memory usage and prevent the client from overwhelming the server or getting stuck in case of a queue backlog. If not set, a default value of 1000 will be used.

lazyConnect?

optional lazyConnect: boolean

Enables lazy connection mode, where physical connections to the server(s) are deferred until the first command is sent. This can reduce startup latency and allow for client creation in disconnected environments.

  • Default: false – connections are established immediately during client creation.

Remarks

When lazyConnect is set to true, the client will not attempt to connect to the specified nodes during initialization. Instead, connections will be established only when a command is actually executed.

Note that the first command executed with lazy connections may experience additional latency as it needs to establish the connection first. During this initial connection, the standard request timeout does not apply yet - instead, the connection establishment is governed by AdvancedBaseClientConfiguration::connectionTimeout. The request timeout (requestTimeout) only begins counting after the connection has been successfully established. This behavior can effectively increase the total time needed for the first command to complete.

This setting applies to both standalone and cluster modes. Note that if an operation is attempted and connection fails (e.g., unreachable nodes), errors will surface at that point.

Example

const client = await GlideClient.createClient({
  addresses: [{ host: "localhost", port: 6379 }],
  lazyConnect: true
});

// No connection is made yet
await client.ping(); // Now the client connects and sends the command

protocol?

optional protocol: ProtocolVersion

Serialization protocol to be used. If not set, RESP3 will be used.

readFrom?

optional readFrom: ReadFrom

The client's read from strategy. If not set, Primary will be used.

requestTimeout?

optional requestTimeout: number

The duration in milliseconds that the client should wait for a request to complete. This duration encompasses sending the request, awaiting for a response from the server, and any required reconnection or retries. If the specified timeout is exceeded for a pending request, it will result in a timeout error. If not explicitly set, a default value of 250 milliseconds will be used. Value must be an integer.

useTLS?

optional useTLS: boolean

True if communication with the cluster should use Transport Level Security. Should match the TLS configuration of the server/cluster, otherwise the connection attempt will fail.