valkey_client 1.2.0

A modern, production-ready Dart client for Valkey (9.0.0+). Fully Redis 7.x compatible.

Valkey client

A modern, production-ready Dart client for Valkey (9.0.0+). Fully Redis 7.x compatible.

---

Recommended Usage: Connection Pooling (v1.1.0+)

For all applications (especially high-concurrency production servers), it is strongly recommended to use the built-in ValkeyPool class instead of connecting/closing individual clients.

The pool manages connections efficiently, preventing performance issues and resource exhaustion.

(See the main Usage example below for a simple case, or the advanced pool example for concurrent requests.)

---

Features

• Built-in Connection Pooling (v1.1.0): ValkeyPool for efficient connection management.
• Broad Command Support:
  • Strings (GET, SET, MGET)
  • 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 (SUBSCRIBE, UNSUBSCRIBE, PSUBSCRIBE, PUNSUBSCRIBE)
  • Pub/Sub Introspection (PUBSUB CHANNELS, NUMSUB, NUMPAT)
• 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: subscribe() returns a Subscription object with a Stream and a Future<void> ready for easy and reliable message handling.
• Production-Ready (Standalone/Sentinel): v1.0.0 is stable for production use in non-clustered environments (when used with a connection pool).

Getting Started

Prerequisites: Running a Valkey Server

This client requires a running Valkey server. For local development, we recommend Docker.

1. Install a container environment like Docker Desktop or Rancher Desktop.
2. Start a Valkey server instance:

Option 1: No Authentication (Default)

docker run -d --name my-valkey -p 6379:6379 valkey/valkey:latest

Option 2: With Password Only (Sets the password for the default user)

docker run -d --name my-valkey-auth -p 6379:6379 valkey/valkey:latest \
  --requirepass "my-super-secret-password"

Option 3: With Username and Password (ACL) (Sets the password for the default user)

docker run -d --name my-valkey-acl -p 6379:6379 valkey/valkey:latest \
  --user default --pass "my-super-secret-password"

• Valkey/Redis 6+ uses ACLs. To create a new user, change --user default to --user my-user.
• The -d flag runs the container in "detached" mode. Remove it to see server logs in your terminal.

Usage

See the Example tab for all examples, including the advanced pool example and the new cluster auto-discovery example.

A simple example (simple_pool_example.dart):

import 'package:valkey_client/valkey_client.dart';

void main() async {
  // 1. Define connection settings
  final settings = ValkeyConnectionSettings(
    host: '127.0.0.1',
    port: 6379,
    // password: 'my-super-secret-password',
  );

  // 2. Create a pool (e.g., max 10 connections)
  final pool = ValkeyPool(connectionSettings: settings, maxConnections: 10);
  ValkeyClient? client;

  try {
    // 3. Acquire a client from the pool
    client = await pool.acquire();
    
    // 4. Run commands
    await client.set('greeting', 'Hello from ValkeyPool!');
    final value = await client.get('greeting');
    print(value); // Output: Hello from ValkeyPool!
    
  } on ValkeyConnectionException catch (e) {
    print('Connection or pool acquisition failed: $e');
  } on ValkeyServerException catch (e) {
    print('Server returned an error: $e');
  } finally {
    // 5. Release the client back to the pool
    if (client != null) {
      pool.release(client);
    }
    // 6. Close the pool when the application shuts down
    await pool.close();
  }
}

---

Contributing

Your contributions are welcome! Please check the GitHub repository for open issues or submit a Pull Request. For major changes, please open an issue first to discuss the approach.

---

Maintained By

Maintained by the developers of Visualkube at Infradise Inc. We believe in giving back to the Dart & Flutter community.

---

License

This project is licensed under the Apache License 2.0.

⚠️ License Change Notification (2025-10-29)

This project was initially licensed under the MIT License. As of October 29, 2025 (v0.11.0 and later), the project has been re-licensed to the Apache License 2.0.

We chose Apache 2.0 for its robust, clear, and balanced terms, which benefit both users and contributors:

• Contributor Protection (Patent Defense): Includes a defensive patent termination clause. This strongly deters users from filing patent infringement lawsuits against contributors (us).
• User Protection (Patent Grant): Explicitly grants users a patent license for any contributor patents embodied in the code, similar to MIT.
• Trademark Protection (Non-Endorsement): Includes a clause (Section 6) that restricts the use of our trademarks (like Infradise Inc. or Visualkube), providing an effect similar to the "non-endorsement" clause in the BSD-3 license.

License Compatibility: Please note that the Apache 2.0 license is compatible with GPLv3, but it is not compatible with GPLv2.

All versions published prior to this change remain available under the MIT License. All future contributions and versions will be licensed under Apache License 2.0.