Crate glide

Expand description

§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};

let client = GlideClusterClient::connect(
    GlideClusterClientConfiguration::with_address("localhost", 7000),
).await?;

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

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.

Re-exports§

pub use types::IntegerReplyOrNoOp;
pub use types::ValueType;
pub use value::FromValkeyValue;
pub use value::ValkeyValue;
pub use value::ValkeyVerbatimFormat;
pub use write::ToSingleValkeyArg;
pub use write::ToValkeyArgs;
pub use write::ValkeyNumericBehavior;
pub use write::ValkeyWrite;
pub use error::GlideError;
pub use routes::Route;
pub use routes::SlotType;
pub use client::ClusterScanCursor;
pub use client::GlideClient;
pub use client::GlideClusterClient;
pub use client::PipelineExt;
pub use client::PubSubMessage;
pub use client::PubSubMessageKind;
pub use config::BackoffStrategy;
pub use config::ClientIdentity;
pub use config::GlideClientConfiguration;
pub use config::GlideClusterClientConfiguration;
pub use config::IamAuthConfig;
pub use config::NodeAddress;
pub use config::NodeDiscoveryMode;
pub use config::PeriodicChecks;
pub use config::ProtocolVersion;
pub use config::PubSubChannelMode;
pub use config::PubSubSubscriptions;
pub use config::ReadFrom;
pub use config::ServerCredentials;
pub use config::ServiceType;
pub use config::TlsConfig;
pub use cmd::Cmd;
pub use cmd::cmd;
pub use commands::core::AsyncCommands;
pub use commands::core::AsyncTypedCommands;
pub use executor::CustomCommand;
pub use commands::core::Commands;
pub use commands::core::TypedCommands;
pub use commands::options::ClientPauseMode;
pub use commands::options::CopyOptions;
pub use commands::options::Direction;
pub use commands::options::ExistenceCheck;
pub use commands::options::ExpireOption;
pub use commands::options::Expiry;
pub use commands::options::FieldExistenceCheck;
pub use commands::options::FlushAllOptions;
pub use commands::options::FlushDbOptions;
pub use commands::options::FunctionFlushOptions;
pub use commands::options::FunctionRestorePolicy;
pub use commands::options::HashFieldExpirationOptions;
pub use commands::options::Limit;
pub use commands::options::LposOptions;
pub use commands::options::MigrateOptions;
pub use commands::options::ObjectType;
pub use commands::options::OrderBy;
pub use commands::options::RestoreOptions;
pub use commands::options::SetExpiry;
pub use commands::options::SetOptions;
pub use commands::options::ValueComparison;
pub use commands::bitmap::BitEncoding;
pub use commands::bitmap::BitFieldOffset;
pub use commands::bitmap::BitFieldSubcommand;
pub use commands::bitmap::BitOverflow;
pub use commands::bitmap::BitmapIndexType;
pub use commands::geo::GeoCoord;
pub use commands::geo::GeoSearchOptions;
pub use commands::geo::GeoSearchResult;
pub use commands::geo::GeoSearchShape;
pub use commands::geo::GeoSearchStoreOptions;
pub use commands::geo::GeoUnit;
pub use commands::sorted_set::AggregationType;
pub use commands::sorted_set::LexBound;
pub use commands::sorted_set::ScoreBound;
pub use commands::stream::StreamAddOptions;
pub use commands::stream::StreamAutoClaimOptions;
pub use commands::stream::StreamAutoClaimReply;
pub use commands::stream::StreamClaimOptions;
pub use commands::stream::StreamClaimReply;
pub use commands::stream::StreamEntry;
pub use commands::stream::StreamGroupCreateOptions;
pub use commands::stream::StreamId;
pub use commands::stream::StreamInfoConsumer;
pub use commands::stream::StreamInfoConsumersReply;
pub use commands::stream::StreamInfoGroup;
pub use commands::stream::StreamInfoGroupsReply;
pub use commands::stream::StreamInfoStreamReply;
pub use commands::stream::StreamKey;
pub use commands::stream::StreamMaxlen;
pub use commands::stream::StreamPendingCountReply;
pub use commands::stream::StreamPendingData;
pub use commands::stream::StreamPendingId;
pub use commands::stream::StreamPendingReply;
pub use commands::stream::StreamRangeReply;
pub use commands::stream::StreamReadGroupOptions;
pub use commands::stream::StreamReadOptions;
pub use commands::stream::StreamReadReply;
pub use commands::stream::StreamTrimOptions;
pub use commands::stream::StreamTrimStrategy;
pub use commands::stream::StreamTrimmingMode;
pub use commands::stream::XPendingEntry;
pub use commands::scan::ScanIter;
pub use commands::scan::SyncScanIter;
pub use script::Script;
pub use script::ScriptInvocation;
pub use pipeline::Pipeline;
pub use pipeline::pipe;
pub use pipeline_options::PipelineOptions;
pub use commands::prelude::*;

Modules§

client: The async GLIDE clients.
cmd: GLIDE’s owned command builder.
commands: Command families. Each submodule is an extension trait with a blanket impl over crate::executor::CommandExecutor, so every client gets every command.
config: Client configuration.
error: Error types for the GLIDE Rust client.
executor: The command dispatch trait.
pipeline: GLIDE’s owned pipeline / transaction builder.
pipeline_options: GLIDE execution options for crate::Pipelines.
routes: Request routing for cluster clients.
script: Lua script helper (Script): SHA-caching EVALSHA with EVAL fallback.
sync: Blocking (synchronous) clients.
telemetry: OpenTelemetry integration.
types: Typed reply types returned by crate::AsyncTypedCommands and crate::TypedCommands.
value: Valkey reply value types.
write: Valkey command argument encoding.

Structs§

BigInt: A big signed integer type.
Bytes: A cheaply cloneable and sliceable chunk of contiguous memory.

Type Aliases§

ValkeyFuture: The future returned by GLIDE async commands.
ValkeyResult: The result type for GLIDE sync operations.

Crate glide

Crate glide Copy item path

§Valkey GLIDE for Rust (glide)

§Highlights

§Documentation

§Supported Engine Versions

§Installation

§Prerequisites

§1. Get the source

§2. Build

§Contributor setup

§Quick start (async)

§Quick start (sync)

§Cluster & routing

§Migrating from redis-rs

§Testing

§Status & publishing

§Getting Help

§Contributing

§License

Re-exports§

Modules§

Structs§

Type Aliases§

Crate glide

§Valkey GLIDE for Rust (`glide`)