Introduction

The valkey_client is a smart client for Valkey and Redis, supporting Standalone, Sentinel, and Cluster modes with auto-failover, smart connection pooling, sharded Pub/Sub, multi-key operations, command timeouts, RESP3 parsing, type-safe exceptions, and built-in logger, SSL/TLS.

Helpers

👉 To browse Redis/Valkey data, you can use Keyscope, a native Redis/Valkey IDE to edit key-value data in your databases.
👉 To access Redis/Valkey servers on Kubernetes, you can use Visualkube Jet, a native Kubernetes IDE for multi‑cluster access and real-time watch.

Keyscope and Visualkube Jet are plugins for Android Studio and JetBrains IDEs.

Features

• Enterprise Security (v2.0.0+): Native SSL/TLS support for secure communication. Fully compatible with major cloud providers (AWS, Azure, GCP) and supports custom security contexts (including self-signed certificates).
• Automatic Failover: The client now survives node failures. If a master node goes down (connection refused/timeout), the client automatically refreshes the cluster topology and reroutes commands to the new master without throwing an exception.
• Connection Pool Hardening: Implemented Smart Release mechanism. The pool automatically detects and discards "dirty" connections (e.g., inside Transaction or Pub/Sub) upon release, preventing pool pollution and resource leaks.
• Enhanced Developer Experience: Expanded Redis aliases to include Exceptions, Configuration, and Data Models (RedisException, RedisMessage, etc.) for a seamless migration experience.
• Sharded Pub/Sub & Atomic Counters: Added support for high-performance cluster messaging (SPUBLISH/SSUBSCRIBE) and atomic integer operations (INCR/DECR).
• Developer Experience: Added RedisClient alias and smart redirection handling for better usability and stability.
• High Availability & Resilience: Automatically and transparently handles cluster topology changes (-MOVED and -ASK redirections) to ensure robust failover, seamless scaling, and zero‑downtime operations.
• Multi-key Support: Supports MGET across multiple nodes using smart Scatter-Gather pipelining.
• Cluster Client: Added ValkeyClusterClient for automatic command routing in cluster mode.
  • This client automatically routes commands to the correct node.
  • We recommend using ValkeyClient for Standalone/Sentinel and ValkeyClusterClient for cluster environments.
• Built-in Connection Pooling: ValkeyPool for efficient connection management (used by Standalone and Cluster clients).
• Cluster Auto-Discovery: Added client.clusterSlots() to fetch cluster topology (via the CLUSTER SLOTS command), laying the foundation for full cluster support.
• Command Timeout: Includes a built-in command timeout (via ValkeyConnectionSettings) to prevent client hangs on non-responsive servers.
• Robust Parsing: Full RESP3 parser handling all core data types (+, -, $, *, :).
• Type-Safe Exceptions: Clear distinction between connection errors (ValkeyConnectionException), server errors (ValkeyServerException), and client errors (ValkeyClientException).
• Pub/Sub Ready (Standalone/Sentinel): subscribe() returns a Subscription object with a Stream and a Future<void> ready for easy and reliable message handling.
• Production-Ready (Standalone/Sentinel): stable for production use in non-clustered environments.
• Production-Ready (Cluster): stable for production use with full cluster support.

Command Support

• Connection (PING, ECHO, QUIT via close())
• Cluster (CLUSTER SLOTS, ASKING)
• Strings (GET, SET, MGET, INCR, DECR, INCRBY, DECRBY)
• Hashes (HSET, HGET, HGETALL)
• Lists (LPUSH, RPUSH, LPOP, RPOP, LRANGE)
• Sets (SADD, SREM, SMEMBERS)
• Sorted Sets (ZADD, ZREM, ZRANGE)
• Key Management (DEL, EXISTS, EXPIRE, TTL)
• Transactions (MULTI, EXEC, DISCARD)
• Full Pub/Sub (PUBLISH, SUBSCRIBE, UNSUBSCRIBE, PSUBSCRIBE, PUNSUBSCRIBE)
• Pub/Sub Introspection (PUBSUB CHANNELS, PUBSUB NUMSUB, PUBSUB NUMPAT)
• Sharded Pub/Sub (SPUBLISH, SSUBSCRIBE, SUNSUBSCRIBE) for efficient cluster messaging.

Developer Experience Improvements

To enhance DX for both Redis and Valkey developers, we provide fully compatible aliases. You can use the class names you are most comfortable with.

• For instance, RedisClient is available as an alias of ValkeyClient to enhance developer experience (DX).
• Both classes and helper functions are fully compatible — choose whichever name feels natural for your project.

Clients

Configuration

Data Models

Exceptions (Crucial for try-catch blocks)

Usage

Refer to the Wiki page in our GitHub repository to see more examples.

1. Example for Standalone or Sentinel environment

import 'package:valkey_client/redis_client.dart';

void main() async {
  final client = RedisClient();
  try {
    await client.connect(
      host: '127.0.0.1',
      port: 6379
    );
    await client.set('key', 'value');
    print(await client.get('key'));

  } catch (e) {
    print('❌ Failed: $e');
  } finally {
    await client.close();
  }
}

import 'package:valkey_client/valkey_client.dart';

void main() async {
  final client = ValkeyClient();
  try {
    await client.connect(
      host: '127.0.0.1',
      port: 6379
    );
    await client.set('key', 'value');
    print(await client.get('key'));

  } catch (e) {
    print('❌ Failed: $e');
  } finally {
    await client.close();
  }
}

2. Example for Cluster environment

import 'package:valkey_client/redis_client.dart';

void main() async {

  final nodes = [
    RedisConnectionSettings(
      host: '127.0.0.1',
      port: 7001,
    ),
  ];

  final client = RedisClusterClient(nodes);
  try {
    await client.connect();
    
    await client.set('key', 'value');
    print(await client.get('key'));

  } catch (e) {
    print('❌ Failed: $e');
  } finally {
    await client.close();
  }
}

import 'package:valkey_client/valkey_client.dart';

void main() async {

  final nodes = [
    ValkeyConnectionSettings(
      host: '127.0.0.1',
      port: 7001,
    ),
  ];

  final client = ValkeyClusterClient(nodes);
  try {
    await client.connect();

    await client.set('key', 'value');
    print(await client.get('key'));

  } catch (e) {
    print('❌ Failed: $e');
  } finally {
    await client.close();
  }
}