valkey-glide 0.9.0

Valkey GLIDE — native Rust client for Valkey and Redis OSS, built on glide-core.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

# Valkey GLIDE for Rust (`glide`)

[![crates.io](https://img.shields.io/crates/v/valkey-glide.svg)](https://crates.io/crates/valkey-glide)
[![docs.rs](https://img.shields.io/docsrs/valkey-glide)](https://docs.rs/valkey-glide)
[![CI](https://github.com/valkey-io/valkey-glide/actions/workflows/rust.yml/badge.svg)](https://github.com/valkey-io/valkey-glide/actions/workflows/rust.yml)
[![Rust](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fvalkey-io%2Fvalkey-glide%2Fmain%2Frust%2FCargo.toml&query=%24.package%5B%27rust-version%27%5D&label=rust&suffix=%2B&color=orange)](https://www.rust-lang.org)

A first-class, native **Rust** client for [Valkey](https://valkey.io) 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 the API
  surface.

## Documentation

GLIDE concepts — cluster routing, [batching](https://glide.valkey.io/concepts/client-features/batch-commands/),
the [PubSub model](https://glide.valkey.io/concepts/client-features/pubsub-model/),
[multi-slot command handling](https://glide.valkey.io/concepts/client-features/multi-slot-command-handling/),
and [OpenTelemetry](https://glide.valkey.io/concepts/client-features/open-telemetry/) —
are shared with the official clients and documented at
[glide.valkey.io](https://glide.valkey.io); this client is built on the same core,
so those concepts apply here unchanged. For Rust-specific architecture see
[DESIGN.md](https://github.com/valkey-io/valkey-glide/blob/main/rust/DESIGN.md).

## Supported Engine Versions

The compatibility target matches GLIDE — see the
[Supported Engine Versions table](https://github.com/valkey-io/valkey-glide/blob/main/README.md#supported-engine-versions).
It is tested on Linux (x86_64 and aarch64). Other platforms (e.g. macOS)
should work wherever `glide-core` builds, but are not tested yet.

## Installation

### Prerequisites

- **Rust** — Install via [rustup](https://rustup.rs).
- 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.

### Add the dependency

The package is named `valkey-glide` and the library is imported as `glide`.
The async client is built on Tokio, so you will also need a Tokio runtime:

```bash
cargo add valkey-glide
cargo add tokio --features rt-multi-thread,macros
```

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

## Quick start (async)

```rust,no_run
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)

```rust,no_run
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

```rust,no_run
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(()) }
```

## 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](https://github.com/valkey-io/valkey-glide/blob/main/rust/migration.md)**
for more details.

## Getting Help

- **GitHub Issues**: Check the [existing issues](https://github.com/valkey-io/valkey-glide/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](https://join.slack.com/t/valkey-oss-developer/shared_invite/zt-2nxs51chx-EB9hu9Qdch3GMfRcztTSkQ).

## Contributing

Contributions are welcome — bug reports, feature requests, and pull requests.
See the [Contributing Guidelines](https://github.com/valkey-io/valkey-glide/blob/main/CONTRIBUTING.md)
to get started and [DEVELOPER.md](https://github.com/valkey-io/valkey-glide/blob/main/rust/DEVELOPER.md)
for the development workflow.

## License

Licensed under the Apache License, Version 2.0. See the
[`LICENSE`](https://github.com/valkey-io/valkey-glide/blob/main/LICENSE)
for the full text.