valkey_client 3.5.1

A high-performance, cluster-aware Dart client for Redis and Valkey.

⚠️ Renamed to TypeRedis

This package (valkey_client) has been renamed to TypeRedis. Please update your dependencies to use the new package for future updates and support.

---

valkey_client ⚡

The high-performance, cluster-aware Dart client for Redis and Valkey.

Supported Commands • Usage • Need help? • Features

Supported Commands

Core Data Types

Basic data structures and generic key operations.

• STRING / HASH / LIST / SET / SORTED SET
• BITMAP / HYPERLOGLOG / GEOSPATIAL INDICES / STREAM
• GENERIC (Keys, Expiration, etc.)

Modules & Extensions

Advanced data types and query engines (JSON, Search, Probabilistic structures).

• JSON / SEARCH / TIME SERIES / VECTOR SET
• BLOOM FILTER / CUCKOO FILTER
• COUNT-MIN SKETCH / T-DIGEST SKETCH / TOP-K SKETCH

System & Operations

Server management, connection handling, and flow control.

• CONNECTION / SERVER / CLUSTER
• PUBSUB / TRANSACTIONS / SCRIPTING AND FUNCTIONS

Usage

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

1. Example for Standalone or Sentinel environment

For Redis users 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(); } }

For Valkey users 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

For Redis users 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(); } }

For Valkey users 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(); } }

Need help?

1. Still using Redis instead of Valkey? Check out Developer Experience Improvements
2. No GUI for Redis/Valkey? Try Keyscope Jet
3. Looking for a GUI built with valkey_client? Try Keyscope
4. Need real‑time watch for Redis/Valkey pods and services across multiple K8s clusters? Try Visualkube Jet

Features

🚀 Performance & Scalability

Feature	Description
Scalable Replica Reads	Boost read performance by offloading read-only commands (e.g., GET, EXISTS) to replica nodes. Supports ReadPreference settings (master, preferReplica, replicaOnly) to control traffic flow.
Smart Load Balancing	Built-in load balancing strategies (Round-Robin, Random) to efficiently distribute read traffic across available replicas.
Multi-key Support	Supports MGET across multiple nodes using smart Scatter-Gather pipelining.
Sharded Pub/Sub & Atomic Counters	Added support for high-performance cluster messaging (SPUBLISH/SSUBSCRIBE) and atomic integer operations (INCR/DECR).

🛡️ High Availability & Resilience

Feature	Description
Automatic Failover	Resilience: 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.
High Availability & Resilience	Automatically and transparently handles cluster topology changes (-MOVED and -ASK redirections) to ensure robust failover, seamless scaling, and zero‑downtime operations.
Automatic Replica Discovery	Automatically detects and connects to replica nodes via INFO REPLICATION (Standalone/Sentinel) to maintain an up-to-date pool of connections.
Cluster Auto-Discovery	Added client.clusterSlots() to fetch cluster topology (via the CLUSTER SLOTS command), laying the foundation for full cluster support.

🧩 Developer Experience & Tooling

Feature	Description
Redis/Valkey Module Detector	Retrieves module metadata to identify installed extensions (e.g., json, search, ldap, bf).
JSON Module Checker	Pre-validates JSON module availability before execution.
Server Metadata Discovery	Access server details via client.metadata (Version, Mode, Server Name, Max Databases) to write adaptive logic for Valkey vs. Redis.
Enhanced Developer Experience	Expanded Redis aliases to include Exceptions, Configuration, and Data Models (RedisException, RedisMessage, etc.) for a seamless migration experience.
Developer Experience	Added RedisClient alias and smart redirection handling for better usability and stability.
Type-Safe Exceptions	Clear distinction between connection errors (ValkeyConnectionException), server errors (ValkeyServerException), and client errors (ValkeyClientException).
Observability	Built-in logging.

🔌 Connection & Configuration

Feature	Description
Smart Database Selection	First-class support for selecting databases (0-15+) on connection. Automatically detects Valkey 9.0+ Numbered Clusters to enable multi-database support in cluster mode, while maintaining backward compatibility with Redis Clusters (DB 0 only).
Explicit Replica Configuration	Added explicitReplicas to ValkeyConnectionSettings to manually define replica nodes, solving connectivity issues in environments where auto-discovery fails.
Cluster Client	ValkeyClusterClient: Dedicated client for automatic command routing in cluster mode. 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).
Connection Pool Hardening	Smart Release Mechanism: Prevents pool pollution by automatically detecting and discarding "dirty" connections (e.g., inside Transaction or Pub/Sub) upon release.
Command Timeout	Includes a built-in command timeout (via ValkeyConnectionSettings) to prevent client hangs on non-responsive servers.

🔒 Security & Core

Feature	Description
Enterprise Security	Native SSL/TLS support compatible with major cloud providers (AWS, Azure, GCP). Supports custom security contexts (including self-signed certificates).
Robust Parsing	Full RESP3 parser handling all core data types (+, -, $, *, :).
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. Cluster: Stable for production use with full cluster support.