redis-rb

# redis-rb [![Build Status][gh-actions-image]][gh-actions-link] [![Inline docs][rdoc-master-image]][rdoc-master-link]

A Ruby client that tries to match [Redis][redis-home]' API one-to-one, while still providing an idiomatic interface.

See [RubyDoc.info][rubydoc] for the API docs of the latest published gem.

## Getting started

Install with:

```
$ gem install redis
```

You can connect to Redis by instantiating the `Redis` class:

```ruby
require "redis"

redis = Redis.new
```

This assumes Redis was started with a default configuration, and is
listening on `localhost`, port 6379. If you need to connect to a remote
server or a different port, try:

```ruby
redis = Redis.new(host: "10.0.1.1", port: 6380, db: 15)
```

You can also specify connection options as a [`redis://` URL][redis-url]:

```ruby
redis = Redis.new(url: "redis://:p4ssw0rd@10.0.1.1:6380/15")
```

The client expects passwords with special characters to be URL-encoded (i.e.
`CGI.escape(password)`).

To connect to Redis listening on a Unix socket, try:

```ruby
redis = Redis.new(path: "/tmp/redis.sock")
```

To connect to a password protected Redis instance, use:

```ruby
redis = Redis.new(password: "mysecret")
```

To connect a Redis instance using [ACL](https://redis.io/topics/acl), use:

```ruby
redis = Redis.new(username: 'myname', password: 'mysecret')
```

The Redis class exports methods that are named identical to the commands
they execute. The arguments these methods accept are often identical to
the arguments specified on the [Redis website][redis-commands]. For
instance, the `SET` and `GET` commands can be called like this:

```ruby
redis.set("mykey", "hello world")
# => "OK"

redis.get("mykey")
# => "hello world"
```

All commands, their arguments, and return values are documented and
available on [RubyDoc.info][rubydoc].

## Language and server support

redis-rb targets actively supported runtimes on both the language and the server side:

- **Ruby:** Ruby 3.2 and newer. See the [Ruby maintenance branches][ruby-branches] page for
  each version's status and dates.
- **Redis server:** the versions designated for support by Redis. See 
[Supported Redis database versions][redis-versions].

## Protocol (RESP3)

Starting in 6.0, the client negotiates the [RESP3 protocol][resp3] (`HELLO 3`)
by default. Command return values are unchanged from 5.x, with one exception:
`GEOPOS` and `GEOSEARCH`/`GEORADIUS` with `WITHCOORD` now return coordinates as
`Float` instead of `String`.

To keep the previous RESP2 behavior, pass `protocol: 2`:

```ruby
redis = Redis.new(protocol: 2)
```

Servers without RESP3 support (Redis < 6.0, or anything replying `NOPROTO`) are
detected on connect and the client transparently falls back to RESP2, so no
configuration is needed for older servers.

### Why RESP3 is the default

RESP3's richer wire types let the parser deliver replies already in their final
Ruby shape. Under RESP2, structured replies arrive as flat arrays of bulk
strings and the client