Valkey GLIDE for Ruby

Valkey General Language Independent Driver for the Enterprise (GLIDE) is the official open-source Valkey client library, proudly part of the Valkey organization. The Ruby gem (valkey-rb) wraps Valkey GLIDE Core (Rust) and aims to be a drop-in replacement for redis-rb while delivering GLIDE performance, reliability, and enterprise features.

Why Choose Valkey GLIDE?

  • Community and Open Source: Join our vibrant community and contribute to the project.
  • 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.
  • Drop-in Replacement: Familiar redis-rb-style API (Valkey.new, command methods, pipelined, URL parsing).
  • Observability: Native OpenTelemetry tracing and client statistics.

Documentation

Supported Engine Versions

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

Getting Started — Ruby Wrapper

System Requirements

The release of Valkey GLIDE Ruby was tested on the following platforms:

Linux:

  • Ubuntu 20+ (x86_64/amd64 and arm64/aarch64)
  • Amazon Linux 2 (AL2) and 2023 (AL2023) (x86_64)

Note: Alpine Linux / MUSL is not currently supported.

macOS:

  • macOS 14.7+ (Apple silicon / aarch64)
  • macOS 13.7+ (x86_64 / amd64)

Ruby Supported Versions

Ruby Version MRI JRuby
2.6 ✓ -
2.7 ✓ -
3.0 – 3.4 ✓ ✓

Minimum Ruby version: 2.6.0 (see valkey.gemspec).

Installation and Setup

Install from RubyGems:

gem install valkey-rb

Or add to your Gemfile:

gem "valkey-rb"

Verify installation:

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

The gem ships prebuilt native libraries (libglide_ffi.so on Linux, libglide_ffi.dylib on macOS) and depends on the ffi gem.

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

Standalone with URL (redis-rb compatible)

client = Valkey.new(url: "redis://localhost:6379/0")
# TLS: rediss://user:password@localhost:6380/0

client.ping
# => "PONG"

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"

Pipelining

Batch multiple commands in a single network round trip (non-atomic pipeline):

results = client.pipelined do |pipe|
  pipe.set("key1", "value1")
  pipe.get("key1")
  pipe.incr("counter")
end
# => ["OK", "value1", 1]

Note: Transactional commands (MULTI / EXEC / DISCARD) in a pipeline are executed sequentially as a workaround for FFI batch stability. Prefer multi / exec on the main client for transactions.

Connection Options (redis-rb compatible)

Option Description
host, port Server address (default 127.0.0.1:6379)
url redis:// or rediss:// URI (merged with explicit options)
db Database index (standalone only)
password, username Authentication
timeout Request timeout in seconds (default 5.0)
connect_timeout Connection timeout in seconds
ssl, ssl_params TLS (ca_file, cert, key, ca_path, root_certs)
cluster_mode Enable cluster client
nodes Array of { host:, port: } hashes
protocol :resp2 (default) or :resp3
client_name CLIENT SETNAME value
reconnect_attempts, reconnect_delay, reconnect_delay_max Connection retry strategy 
client = Valkey.new(
  host: "localhost",
  port: 6379,
  timeout: 2.0,
  connect_timeout: 1.0,
  client_name: "my-app",
  protocol: :resp3
)

OpenTelemetry

Valkey GLIDE Ruby configures OpenTelemetry in the native Rust core (not via the Ruby opentelemetry-sdk gem). Initialize once per process before creating clients:

require "valkey"

Valkey::OpenTelemetry.init(
  traces: {
    endpoint: "http://localhost:4318/v1/traces",
    sample_percentage: 10
  },
  metrics: {
    endpoint: "http://localhost:4318/v1/metrics"
  },
  flush_interval_ms: 5000
)

client = Valkey.new(host: "localhost", port: 6379)
client.set("key", "value")  # traced when sampling applies

Supported endpoint formats:

  • HTTP/HTTPS: http://localhost:4318/v1/traces
  • gRPC: grpc://localhost:4317
  • File (testing): file:///tmp/valkey_traces.json

OpenTelemetry can only be initialized once per process. Spans are created in the FFI layer when sampling is enabled.

Examples

Runnable examples are in examples/:

bundle exec ruby examples/standalone.rb
bundle exec ruby examples/pipelining.rb
bundle exec ruby examples/opentelemetry.rb

See examples/README.md for cluster setup and environment variables.

Client Statistics

Monitor global client metrics (shared across all clients in the process):

stats = client.get_statistics
# alias: client.statistics

puts "Connections: #{stats[:total_connections]}"
puts "Clients: #{stats[:total_clients]}"
puts "Compressed values: #{stats[:total_values_compressed]}"

Available keys: :total_connections, :total_clients, :total_values_compressed, :total_values_decompressed, :total_original_bytes, :total_bytes_compressed, :total_bytes_decompressed, :compression_skipped_count.

Pub/Sub

Pub/Sub uses a native callback registered at connection time. Configure subscriptions via command modules (subscribe, psubscribe, etc.). See DEVELOPER.md and integration tests in test/valkey/pubsub_commands_test.rb for details.

Layout of Ruby Code

Path Purpose
lib/valkey.rb Main client: connection, pipelining, response conversion
lib/valkey/bindings.rb FFI bindings to libglide_ffi
lib/valkey/commands/ Command modules (strings, hashes, streams, cluster, JSON, vector search, …)
lib/valkey/opentelemetry.rb OpenTelemetry configuration
lib/valkey/pipeline.rb Pipeline command batching
test/valkey/ Standalone integration tests
test/cluster/ Cluster integration tests
test/lint/ Shared lint tests (redis-rb compatibility patterns)

redis-rb Compatibility

This client mirrors redis-rb conventions where possible:

  • Valkey.new with url, host, port, db, ssl_params
  • Command method names and argument ordering aligned with redis-rb
  • pipelined, multi / exec, disconnect! (alias of close)

Not every redis-rb API is implemented yet. See the command implementation wiki for coverage.

Building and Testing

Instructions for building from source, updating the FFI library, running tests, and contributing are in DEVELOPER.md.

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

Contributing: CONTRIBUTING.md.

Community and Feedback

We encourage you to join our community to support, share feedback, and ask questions on Valkey Slack: Join Valkey Slack.

Report issues: valkey-glide-ruby issues.

License

Apache-2.0 — see LICENSE in the repository.