README.md
1# Redis client for Golang
2
3[](https://travis-ci.org/go-redis/redis)
4[](https://godoc.org/github.com/go-redis/redis)
5[](https://airbrake.io)
6
7Supports:
8
9- Redis 3 commands except QUIT, MONITOR, SLOWLOG and SYNC.
10- Automatic connection pooling with [circuit breaker](https://en.wikipedia.org/wiki/Circuit_breaker_design_pattern) support.
11- [Pub/Sub](https://godoc.org/github.com/go-redis/redis#PubSub).
12- [Transactions](https://godoc.org/github.com/go-redis/redis#example-Client-TxPipeline).
13- [Pipeline](https://godoc.org/github.com/go-redis/redis#example-Client-Pipeline) and [TxPipeline](https://godoc.org/github.com/go-redis/redis#example-Client-TxPipeline).
14- [Scripting](https://godoc.org/github.com/go-redis/redis#Script).
15- [Timeouts](https://godoc.org/github.com/go-redis/redis#Options).
16- [Redis Sentinel](https://godoc.org/github.com/go-redis/redis#NewFailoverClient).
17- [Redis Cluster](https://godoc.org/github.com/go-redis/redis#NewClusterClient).
18- [Cluster of Redis Servers](https://godoc.org/github.com/go-redis/redis#example-NewClusterClient--ManualSetup) without using cluster mode and Redis Sentinel.
19- [Ring](https://godoc.org/github.com/go-redis/redis#NewRing).
20- [Instrumentation](https://godoc.org/github.com/go-redis/redis#ex-package--Instrumentation).
21- [Cache friendly](https://github.com/go-redis/cache).
22- [Rate limiting](https://github.com/go-redis/redis_rate).
23- [Distributed Locks](https://github.com/bsm/redislock).
24
25API docs: https://godoc.org/github.com/go-redis/redis.
26Examples: https://godoc.org/github.com/go-redis/redis#pkg-examples.
27
28## Installation
29
30go-redis requires a Go version with [Modules](https://github.com/golang/go/wiki/Modules) support and uses import versioning. So please make sure to initialize a Go module before installing go-redis:
31
32``` shell
33go mod init github.com/my/repo
34go get github.com/go-redis/redis/v7
35```
36
37Import:
38
39``` go
40import "github.com/go-redis/redis/v7"
41```
42
43## Quickstart
44
45``` go
46func ExampleNewClient() {
47 client := redis.NewClient(&redis.Options{
48 Addr: "localhost:6379",
49 Password: "", // no password set
50 DB: 0, // use default DB
51 })
52
53 pong, err := client.Ping().Result()
54 fmt.Println(pong, err)
55 // Output: PONG <nil>
56}
57
58func ExampleClient() {
59 client := redis.NewClient(&redis.Options{
60 Addr: "localhost:6379",
61 Password: "", // no password set
62 DB: 0, // use default DB
63 })
64 err := client.Set("key", "value", 0).Err()
65 if err != nil {
66 panic(err)
67 }
68
69 val, err := client.Get("key").Result()
70 if err != nil {
71 panic(err)
72 }
73 fmt.Println("key", val)
74
75 val2, err := client.Get("key2").Result()
76 if err == redis.Nil {
77 fmt.Println("key2 does not exist")
78 } else if err != nil {
79 panic(err)
80 } else {
81 fmt.Println("key2", val2)
82 }
83 // Output: key value
84 // key2 does not exist
85}
86```
87
88## Howto
89
90Please go through [examples](https://godoc.org/github.com/go-redis/redis#pkg-examples) to get an idea how to use this package.
91
92## Look and feel
93
94Some corner cases:
95
96``` go
97// SET key value EX 10 NX
98set, err := client.SetNX("key", "value", 10*time.Second).Result()
99
100// SORT list LIMIT 0 2 ASC
101vals, err := client.Sort("list", &redis.Sort{Offset: 0, Count: 2, Order: "ASC"}).Result()
102
103// ZRANGEBYSCORE zset -inf +inf WITHSCORES LIMIT 0 2
104vals, err := client.ZRangeByScoreWithScores("zset", redis.ZRangeBy{
105 Min: "-inf",
106 Max: "+inf",
107 Offset: 0,
108 Count: 2,
109}).Result()
110
111// ZINTERSTORE out 2 zset1 zset2 WEIGHTS 2 3 AGGREGATE SUM
112vals, err := client.ZInterStore("out", redis.ZStore{Weights: []int64{2, 3}}, "zset1", "zset2").Result()
113
114// EVAL "return {KEYS[1],ARGV[1]}" 1 "key" "hello"
115vals, err := client.Eval("return {KEYS[1],ARGV[1]}", []string{"key"}, "hello").Result()
116
117// custom command
118res, err := client.Do("set", "key", "value").Result()
119```
120
121## See also
122
123- [Golang PostgreSQL ORM](https://github.com/go-pg/pg)
124- [Golang msgpack](https://github.com/vmihailenco/msgpack)
125- [Golang message task queue](https://github.com/vmihailenco/taskq)
126
){kind=link}
){kind=link}
){kind=link}