Valkey GLIDE for Rust (glide)

A first-class, native Rust client for Valkey and Redis OSS, built directly on the shared glide-core engine that powers the official GLIDE clients for Python, Java, Node, and Go.

Because glide-core is itself written in Rust, this wrapper links to it directly — no FFI, no socket bridge — making it the thinnest and fastest GLIDE binding.

Highlights

• Async first — GlideClient (standalone) and GlideClusterClient (cluster) built on Tokio.
• Blocking API — a sync layer mirrors the async surface for non-async code (enabled by the default sync feature).
• Broad command coverage — typed methods across strings, generic/key, hash, list, set, sorted-set, HyperLogLog, bitmap, geo, stream, scripting, connection- and server-management, plus batches/transactions.
• custom_command escape hatch — run any command (with optional cluster routing) even where a typed wrapper is not provided, guaranteeing 100% functional coverage.
• Batching — pipe() pipelines and MULTI/EXEC transactions, executed typed via query_async (zero extra payload copies) or with GLIDE execution controls (PipelineOptions: per-call timeout and pipeline retry strategy) via exec.
• Dynamic authentication — rotate the connection password at runtime with update_connection_password, or use AWS IAM auth (ElastiCache / MemoryDB) via ServerCredentials::iam.
• Runtime Pub/Sub — subscribe/psubscribe/ssubscribe (and the matching unsubscribes) in addition to connect-time subscriptions; messages arrive via get_pubsub_message.
• OpenTelemetry — export traces and metrics via the glide::telemetry module (gRPC / HTTP / file exporters).
• Feature parity with the Python GLIDE wrapper as the baseline for both the API surface and the test suite.

Documentation

GLIDE concepts — cluster routing, batching, the PubSub model, multi-slot command handling, and OpenTelemetry — are shared with the official clients and documented at glide.valkey.io; this client is built on the same core, so those concepts apply here unchanged. For Rust-specific architecture see DESIGN.md.

Supported Engine Versions

The compatibility target matches GLIDE — see the Supported Engine Versions table. CI runs the full integration suite against Valkey 8.1, 8.0, and 7.2 and Redis OSS 7.2, on Linux (x86_64 and aarch64). Other platforms (e.g. macOS) should work wherever glide-core builds, but are not exercised in CI.

Installation

Prerequisites

• Rust — install via rustup
• A monorepo checkout — this crate lives in the valkey-io/valkey-glide monorepo under rust/ and links glide-core and redis-rs via in-repo path dependencies (see Status & publishing).
• A running Valkey (or Redis OSS) server to connect to — e.g. valkey-server locally, docker run -p 6379:6379 valkey/valkey, or an ElastiCache/MemoryDB endpoint.

1. Get the source

This crate is not yet on crates.io and links glide-core and its vendored redis-rs via in-repo path dependencies (see Status & publishing), so it is currently built from a checkout of the valkey-io/valkey-glide monorepo rather than added as an external dependency. The package is named valkey-glide and the library is imported as glide; you will also need an async runtime (the async client is built on Tokio):

# Cargo.toml
[dependencies]
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

Once the dependency chain is published to crates.io, this section will document the versioned-dependency setup.

2. Build

cargo build

The first build fetches and compiles glide-core and its dependency tree, so it takes a few minutes; subsequent builds are incremental.

Contributor setup

Cloning this repository to develop the client? See DEVELOPER.md for the full workflow (build, run the unit + live integration tests — which spawn a valkey-server, set VALKEY_SERVER_PATH to point at your binary — lint, and coverage).

Quick start (async)

use glide::{AsyncCommands, GlideClient, GlideClientConfiguration};

#[tokio::main]
async fn main() -> glide::ValkeyResult<()> {
    let config = GlideClientConfiguration::with_address("localhost", 6379);
    let client = GlideClient::connect(config).await.expect("connect");

    client.set::<_, _, ()>("hello", "world").await?;
    let value: Option<String> = client.get("hello").await?;
    assert_eq!(value.as_deref(), Some("world"));
    Ok(())
}

Quick start (sync)

use glide::sync::SyncGlideClient;
use glide::{Commands, GlideClientConfiguration};

fn main() -> glide::ValkeyResult<()> {
    let client = SyncGlideClient::connect(
        GlideClientConfiguration::with_address("localhost", 6379),
    ).expect("connect");
    client.set::<_, _, ()>("hello", "world")?;
    let value: Option<String> = client.get("hello")?;
    assert_eq!(value.as_deref(), Some("world"));
    Ok(())
}

Cluster & routing

use glide::{GlideClusterClient, GlideClusterClientConfiguration, Route, CustomCommand};

# async fn demo() -> glide::ValkeyResult<()> {
let client = GlideClusterClient::connect(
    GlideClusterClientConfiguration::with_address("localhost", 7000),
).await?;

// Broadcast PING to all primaries.
client.custom_command_with_route(&["PING"], Route::AllPrimaries).await?;
# Ok(()) }

See DESIGN.md for architecture, and DEVELOPER.md for how to build and test.

Migrating from redis-rs

GLIDE's command API mirrors redis-rs 1.7.0, so most call sites migrate with only import and type-name changes. See migration.md for more details.

Testing

The suite has three layers (all run in CI and are currently green):

• Unit tests (server-free, ~260) — pure logic with no server: config → ConnectionRequest lowering, route → RoutingInfo mapping, option/argument encoding, value conversion, and error mapping; plus a command-family mock suite that drives every typed command through an in-process executor to assert exact request encoding and response decoding.
• Integration tests (live server) — real round-trips against a spawned valkey-server, one tests/it_<family>.rs per command family with edge/error cases (wrong-type, missing key, bounds, expiry conditions), parametrized over RESP2 and RESP3, plus suites for batches, scan, pub/sub, auth, TLS, and a native multi-shard cluster harness. Each test boots its own ephemeral server and tears it down on drop; a test fails if its server or cluster cannot be started.
• Doctests — the examples in this README and the API docs are compiled.

cargo unit-tests         # unit tests
cargo doc-tests          # doctests
cargo integration-tests  # integration tests
cargo test               # all tests (unit, docs, and integration)

Integration tests auto-discover a valkey-server/redis-server on PATH; point them at a specific binary with VALKEY_SERVER_PATH=/path/to/valkey-server. See DEVELOPER.md for coverage.

Status & publishing

This crate lives in the valkey-io/valkey-glide monorepo and links glide-core and its vendored redis-rs via in-repo path dependencies (see DEVELOPER.md). Consequences to be aware of:

• Builds from a monorepo checkout — the path dependencies resolve to the sibling glide-core (and its vendored redis-rs fork) in the same tree, so no network fetch is required to resolve them; you build from a checkout of the monorepo.
• Not yet publishable to crates.io as-is — cargo publish rejects both path and git dependencies, so the crate cannot be published while it links glide-core (and the vendored redis-rs fork) by path. The only route to crates.io is to publish glide-core and the redis-rs fork to crates.io and switch these to versioned dependencies (glide-core = "x.y"); this is tracked as part of #6519. This is an inherent consequence of the "link core directly, no FFI" design and is a deliberate release-time decision.
• docs.rs builds would likewise need the dependency strategy resolved first.

Getting Help

• GitHub Issues: Check the existing issues first; if your question or problem isn't covered, open a new issue.
• Valkey Slack: For questions about Valkey or GLIDE in general, join the Valkey Slack.

Contributing

Contributions are welcome — bug reports, feature requests, and pull requests. See the repo-root Contributing Guidelines to get started and DEVELOPER.md for the development workflow.

License

Licensed under the Apache License, Version 2.0. See the LICENSE for the full text.