@valkey/valkey-glide
    Preparing search index...

    Interface BaseClientConfiguration

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

    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.

    • 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.
    • Database ID: Use databaseId to specify which logical database to connect to (0-15 by default).
      • Cluster Mode: Requires Valkey 9.0+ with multi-database cluster mode enabled.
      • Standalone Mode: Works with all Valkey versions.
      • Reconnection: Database selection persists across reconnections.
    • 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.
    • 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 Name: Set clientName to identify the client connection.
    • Use readFrom to specify the client's read strategy (e.g., primary, preferReplica, AZAffinity, AZAffinityReplicasAndPrimary).
    • Use clientAz to specify the client's availability zone, which can influence read operations when using readFrom: 'AZAffinity'or readFrom: 'AZAffinityReplicasAndPrimary'`.
    • Default Decoder: Set defaultDecoder to specify how responses are decoded by default.
    • Inflight Requests Limit: Control the number of concurrent requests using inflightRequestsLimit.
    • 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, specified in milliseconds (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).
    const config: BaseClientConfiguration = {
      addresses: [
        { host: 'redis-node-1.example.com', port: 6379 },
        { host: 'redis-node-2.example.com' }, // Defaults to port 6379
      ],
      databaseId: 5, // Connect to database 5
      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,
    };
    interface BaseClientConfiguration {
        addresses: { host: string; port?: number }[];
        clientAz?: string;
        clientName?: string;
        connectionBackoff?: {
            exponentBase: number;
            factor: number;
            jitterPercent?: number;
            numberOfRetries: number;
        };
        credentials?: ServerCredentials;
        databaseId?: number;
        defaultDecoder?: Decoder;
        inflightRequestsLimit?: number;
        lazyConnect?: boolean;
        protocol?: ProtocolVersion;
        readFrom?: ReadFrom;
        requestTimeout?: number;
        useTLS?: boolean;
    }
    Index

    Properties

    addresses clientAz? clientName? connectionBackoff? credentials? databaseId? defaultDecoder? inflightRequestsLimit? lazyConnect? protocol? readFrom? requestTimeout? useTLS?

    Properties

    addresses: { host: string; port?: number }[]

    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.

    Type Declaration

    • host: string
    • Optionalport?: number

      If port isn't supplied, 6379 will be used

    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?: 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 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?: string

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

    connectionBackoff?: {
        exponentBase: number;
        factor: number;
        jitterPercent?: number;
        numberOfRetries: number;
    }

    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.

    Type Declaration

    • exponentBase: number

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

    • factor: number

      The multiplier that will be applied to the waiting time between each retry. This value is specified in milliseconds. Value must be an integer.

    • OptionaljitterPercent?: 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: 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?: ServerCredentials

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

    databaseId?: number

    Index of the logical database to connect to.

    • Standalone Mode: Works with all Valkey versions.
    • Cluster Mode: Requires Valkey 9.0+ with multi-database cluster mode enabled.
    • Reconnection: Database selection persists across reconnections.
    • Default: If not specified, defaults to database 0.
    • Range: Must be non-negative. The server will validate the upper limit based on its configuration.
    • Server Validation: The server determines the maximum database ID based on its databases configuration (standalone) or cluster-databases configuration (cluster mode).
    // Connect to database 5
    const config: BaseClientConfiguration = {
      addresses: [{ host: 'localhost', port: 6379 }],
      databaseId: 5
    };

    // Connect to a higher database ID (server will validate the limit)
    const configHighDb: BaseClientConfiguration = {
      addresses: [{ host: 'localhost', port: 6379 }],
      databaseId: 100
    };
    defaultDecoder?: Decoder

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

    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?: 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.

    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.

    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?: ProtocolVersion

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

    readFrom?: ReadFrom

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

    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?: 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.

    Settings

    Member Visibility

    On This Page

    Connection DetailsDatabase SelectionSecurity SettingsCommunication SettingsClient IdentificationRead StrategyAvailability ZoneDecoder SettingsConcurrency ControlReconnection Strategy
    Properties