Valkey GLIDE for Ruby

Valkey General Language Independent Driver for the Enterprise (GLIDE) is the official open-source Valkey client library, part of the Valkey organization. The Ruby gem (valkey-glide-rb) wraps Valkey GLIDE Core, giving Ruby applications the performance and reliability of the GLIDE core.

Features

Community and Open Source: Developed in the open under the Valkey organization; contributions welcome.
Reliability: Built with best practices learned from over a decade of operating Redis OSS-compatible services.
Performance: Optimized for high performance and low latency via the Rust-based GLIDE core.
High Availability: Cluster-aware routing, reconnection, and fault tolerance.
Cross-Language Consistency: Same core driver as Python, Java, Node.js, and Go clients.
Observability: Native OpenTelemetry tracing and client statistics.

Documentation

Valkey GLIDE Documentations: glide.valkey.io
Supported Valkey Commands: GLIDE supported commands
Supported engine versions: valkey-glide README: Supported Engine Versions

Supported Engine Versions

Engine Type	6.2	7.0	7.1	7.2	8.0	8.1	9.0
Valkey	-	-	-	✓	✓	✓	✓
Redis OSS	✓	✓	✓	✓	-	-	-

Getting Started

System Requirements

glibc 2.17+ or musl 1.2.3+
Ruby 3.0+

Supported OS

The following platforms are tested in CI:

Ubuntu 24 (x86_64 and arm64)
Alpine Linux 3 (x86_64 and arm64, via musl targets)
macOS 14+ (Apple silicon / arm64)

Notes: valkey-glide-rb depends on the compiled Rust core. For unsupported OS like Intel Mac, you will need to build Valkey GLIDE manually.

Installation and Setup

Install from RubyGems:

gem install valkey-glide-rb

Or add to your Gemfile:

gem "valkey-glide-rb"

Verify installation:

ruby -e 'require "valkey"; puts Valkey::VERSION'

Basic Examples

Standalone Mode

require "valkey"

client = Valkey.new(host: "localhost", port: 6379)

client.set("mykey", "hello world")
# => "OK"

client.get("mykey")
# => "hello world"

client.close

Cluster Mode

nodes = [
  { host: "127.0.0.1", port: 7000 },
  { host: "127.0.0.1", port: 7001 },
  { host: "127.0.0.1", port: 7002 },
  { host: "127.0.0.1", port: 7003 },
  { host: "127.0.0.1", port: 7004 },
  { host: "127.0.0.1", port: 7005 }
]

client = Valkey.new(nodes: nodes, cluster_mode: true)
client.set("foo", "bar")
client.get("foo")
# => "bar"

Connection Options

Option	Description
`host`, `port`	Server address (default `127.0.0.1:6379`)
`url`	`redis://`, `rediss://`, `valkey://`, or `valkeys://` URI (merged with explicit options)
`db`	Database index (standalone only)
`password`, `username`	Authentication
`iam_config`	A `Valkey::IamAuthConfig` for AWS IAM authentication. Requires `username` and cannot be combined with `password`.
`timeout`	Request timeout in seconds (default `5.0`)
`connect_timeout`	Connection timeout in seconds
`ssl`	Enable TLS if true
`ssl_params`	TLS options {`ca_file`, `cert`, `key`, `ca_path`, `root_certs`}
`cluster_mode`	Enable cluster client
`nodes`	Array of `{ host:, port: }` hashes
`protocol`	`:resp3` (default) or `:resp2`
`client_name`	`CLIENT SETNAME` value
`lib_name`	Full override of the `CLIENT SETINFO LIB-NAME` value (default `GlideRuby`). Accepts a `String`, a `Symbol`, or `nil`. Validated by glide-core: printable ASCII excluding space, `(` and `)`, plus at most one matched trailing `(tag)`; an invalid value raises `Valkey::CannotConnectError` at client creation. An empty value falls back to the default.
`client_info_tag`	Appends a parenthesized tag to the resolved library name while keeping the base token intact — e.g. `GlideRuby(my-framework:1.0)`, or `<lib_name>(<tag>)` when combined with `lib_name`. An empty tag is treated as absent (no suffix). Like `lib_name`, the composed value is validated by glide-core. Note the resolved library name is visible to anyone who can run `CLIENT LIST`/`CLIENT INFO` and may appear in server logs, so do not put secrets or sensitive tenant identifiers in it. Preferred over `lib_name` for framework attribution because it preserves GLIDE adoption visibility.
`reconnect_attempts`, `reconnect_delay`, `reconnect_delay_max`	Connection retry strategy
`read_from`	Read routing: the `Valkey::ReadFrom::*` constants: `PRIMARY`, `PREFER_REPLICA`, `AZ_AFFINITY`, `AZ_AFFINITY_REPLICAS_AND_PRIMARY`.`AZ_AFFINITY`/`AZ_AFFINITY_REPLICAS_AND_PRIMARY` require `client_az` to also be set.
`client_az`	Availability-zone identifier for `AZ_AFFINITY` / `AZ_AFFINITY_REPLICAS_AND_PRIMARY` routing (e.g. `"us-west-2a"`)
`inflight_requests_limit`	Maximum concurrent in-flight requests (non-negative integer)
`lazy_connect`	Delay the actual connection until the first command is sent
`periodic_checks`	Cluster topology health checks: `{ manual_interval: { duration_in_sec: N } }` or `{ disabled: true }`. Accepted (as a no-op) on standalone connections.

Forking Support

A Ruby client currently have limited forking support. After each fork you need to recreate the Valkey instance.

Note: if the parent issues any command before forking, a client created in the child can still be killed by a native signal. This is a limitation of the Rust core, tracked in valkey-glide#6912. Until it ships, do not use Valkey in the parent process.

Building and Testing

For AI-assisted development, see AGENTS.md and CLAUDE.md.

Contributing: CONTRIBUTING.md.

For setting up your local development, see DEVELOPER.md

Community and Feedback

Join the community on Valkey Slack to ask questions and share feedback: Join Valkey Slack.

Report issues: valkey-glide-ruby issues.

License

Apache-2.0. See LICENSE in the repository.

test-valkey-glide-rb

Runtime