Redis client for Go
![Chat](https://discordapp.com/api/guilds/752070105847955518/widget.png)
go-redis is brought to you by :star: uptrace/uptrace.
Uptrace is an open-source APM tool that supports distributed tracing, metrics, and logs. You can
use it to monitor applications and set up automatic alerts to receive notifications via email,
Slack, Telegram, and others.
See OpenTelemetry example which
demonstrates how you can use Uptrace to monitor go-redis.
How do I Redis?
Learn for free at Redis University
Build faster with the Redis Launchpad
Try the Redis Cloud
Dive in developer tutorials
Join the Redis community
Work at Redis
Documentation
Resources
Ecosystem
This client also works with Kvrocks, a distributed
key value NoSQL database that uses RocksDB as storage engine and is compatible with Redis protocol.
Features
Installation
go-redis supports 2 last Go versions and requires a Go version with
modules support. So make sure to initialize a Go
module:
go mod init github.com/my/repo
Then install go-redis/v9:
go get github.com/redis/go-redis/v9
Quickstart
import (
"context"
"fmt"
"github.com/redis/go-redis/v9"
)
var ctx = context.Background()
func ExampleClient() {
rdb := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
Password: "",
DB: 0,
})
err := rdb.Set(ctx, "key", "value", 0).Err()
if err != nil {
panic(err)
}
val, err := rdb.Get(ctx, "key").Result()
if err != nil {
panic(err)
}
fmt.Println("key", val)
val2, err := rdb.Get(ctx, "key2").Result()
if err == redis.Nil {
fmt.Println("key2 does not exist")
} else if err != nil {
panic(err)
} else {
fmt.Println("key2", val2)
}
}
The above can be modified to specify the version of the RESP protocol by adding the protocol
option to the Options
struct:
rdb := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
Password: "",
DB: 0,
Protocol: 3,
})
Connecting via a redis url
go-redis also supports connecting via the
redis uri specification.
The example below demonstrates how the connection can easily be configured using a string, adhering
to this specification.
import (
"github.com/redis/go-redis/v9"
)
func ExampleClient() *redis.Client {
url := "redis://user:password@localhost:6379/0?protocol=3"
opts, err := redis.ParseURL(url)
if err != nil {
panic(err)
}
return redis.NewClient(opts)
}
Advanced Configuration
go-redis supports extending the client identification phase to allow projects to send their own custom client identification.
Default Client Identification
By default, go-redis automatically sends the client library name and version during the connection process. This feature is available in redis-server as of version 7.2. As a result, the command is "fire and forget", meaning it should fail silently, in the case that the redis server does not support this feature.
Disabling Identity Verification
When connection identity verification is not required or needs to be explicitly disabled, a DisableIndentity
configuration option exists. In V10 of this library, DisableIndentity
will become DisableIdentity
in order to fix the associated typo.
To disable verification, set the DisableIndentity
option to true
in the Redis client options:
rdb := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
Password: "",
DB: 0,
DisableIndentity: true,
})
Contributing
Please see out contributing guidelines to help us improve this library!
Look and feel
Some corner cases:
set, err := rdb.SetNX(ctx, "key", "value", 10*time.Second).Result()
set, err := rdb.SetNX(ctx, "key", "value", redis.KeepTTL).Result()
vals, err := rdb.Sort(ctx, "list", &redis.Sort{Offset: 0, Count: 2, Order: "ASC"}).Result()
vals, err := rdb.ZRangeByScoreWithScores(ctx, "zset", &redis.ZRangeBy{
Min: "-inf",
Max: "+inf",
Offset: 0,
Count: 2,
}).Result()
vals, err := rdb.ZInterStore(ctx, "out", &redis.ZStore{
Keys: []string{"zset1", "zset2"},
Weights: []int64{2, 3}
}).Result()
vals, err := rdb.Eval(ctx, "return {KEYS[1],ARGV[1]}", []string{"key"}, "hello").Result()
res, err := rdb.Do(ctx, "set", "key", "value").Result()
Run the test
go-redis will start a redis-server and run the test cases.
The paths of redis-server bin file and redis config file are defined in main_test.go
:
var (
redisServerBin, _ = filepath.Abs(filepath.Join("testdata", "redis", "src", "redis-server"))
redisServerConf, _ = filepath.Abs(filepath.Join("testdata", "redis", "redis.conf"))
)
For local testing, you can change the variables to refer to your local files, or create a soft link
to the corresponding folder for redis-server and copy the config file to testdata/redis/
:
ln -s /usr/bin/redis-server ./go-redis/testdata/redis/src
cp ./go-redis/testdata/redis.conf ./go-redis/testdata/redis/
Lastly, run:
go test
Another option is to run your specific tests with an already running redis. The example below, tests
against a redis running on port 9999.:
REDIS_PORT=9999 go test <your options>
See also
Contributors
Thanks to all the people who already contributed!