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/redis-lock).
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
30Install:
31
32```shell
33go get -u github.com/go-redis/redis
34```
35
36Import:
37
38```go
39import "github.com/go-redis/redis"
40```
41
42## Quickstart
43
44```go
45func ExampleNewClient() {
46 client := redis.NewClient(&redis.Options{
47 Addr: "localhost:6379",
48 Password: "", // no password set
49 DB: 0, // use default DB
50 })
51
52 pong, err := client.Ping().Result()
53 fmt.Println(pong, err)
54 // Output: PONG <nil>
55}
56
57func ExampleClient() {
58 err := client.Set("key", "value", 0).Err()
59 if err != nil {
60 panic(err)
61 }
62
63 val, err := client.Get("key").Result()
64 if err != nil {
65 panic(err)
66 }
67 fmt.Println("key", val)
68
69 val2, err := client.Get("key2").Result()
70 if err == redis.Nil {
71 fmt.Println("key2 does not exist")
72 } else if err != nil {
73 panic(err)
74 } else {
75 fmt.Println("key2", val2)
76 }
77 // Output: key value
78 // key2 does not exist
79}
80```
81
82## Howto
83
84Please go through [examples](https://godoc.org/github.com/go-redis/redis#pkg-examples) to get an idea how to use this package.
85
86## Look and feel
87
88Some corner cases:
89
90```go
91// SET key value EX 10 NX
92set, err := client.SetNX("key", "value", 10*time.Second).Result()
93
94// SORT list LIMIT 0 2 ASC
95vals, err := client.Sort("list", redis.Sort{Offset: 0, Count: 2, Order: "ASC"}).Result()
96
97// ZRANGEBYSCORE zset -inf +inf WITHSCORES LIMIT 0 2
98vals, err := client.ZRangeByScoreWithScores("zset", redis.ZRangeBy{
99 Min: "-inf",
100 Max: "+inf",
101 Offset: 0,
102 Count: 2,
103}).Result()
104
105// ZINTERSTORE out 2 zset1 zset2 WEIGHTS 2 3 AGGREGATE SUM
106vals, err := client.ZInterStore("out", redis.ZStore{Weights: []int64{2, 3}}, "zset1", "zset2").Result()
107
108// EVAL "return {KEYS[1],ARGV[1]}" 1 "key" "hello"
109vals, err := client.Eval("return {KEYS[1],ARGV[1]}", []string{"key"}, "hello").Result()
110```
111
112## Benchmark
113
114go-redis vs redigo:
115
116```
117BenchmarkSetGoRedis10Conns64Bytes-4 200000 7621 ns/op 210 B/op 6 allocs/op
118BenchmarkSetGoRedis100Conns64Bytes-4 200000 7554 ns/op 210 B/op 6 allocs/op
119BenchmarkSetGoRedis10Conns1KB-4 200000 7697 ns/op 210 B/op 6 allocs/op
120BenchmarkSetGoRedis100Conns1KB-4 200000 7688 ns/op 210 B/op 6 allocs/op
121BenchmarkSetGoRedis10Conns10KB-4 200000 9214 ns/op 210 B/op 6 allocs/op
122BenchmarkSetGoRedis100Conns10KB-4 200000 9181 ns/op 210 B/op 6 allocs/op
123BenchmarkSetGoRedis10Conns1MB-4 2000 583242 ns/op 2337 B/op 6 allocs/op
124BenchmarkSetGoRedis100Conns1MB-4 2000 583089 ns/op 2338 B/op 6 allocs/op
125BenchmarkSetRedigo10Conns64Bytes-4 200000 7576 ns/op 208 B/op 7 allocs/op
126BenchmarkSetRedigo100Conns64Bytes-4 200000 7782 ns/op 208 B/op 7 allocs/op
127BenchmarkSetRedigo10Conns1KB-4 200000 7958 ns/op 208 B/op 7 allocs/op
128BenchmarkSetRedigo100Conns1KB-4 200000 7725 ns/op 208 B/op 7 allocs/op
129BenchmarkSetRedigo10Conns10KB-4 100000 18442 ns/op 208 B/op 7 allocs/op
130BenchmarkSetRedigo100Conns10KB-4 100000 18818 ns/op 208 B/op 7 allocs/op
131BenchmarkSetRedigo10Conns1MB-4 2000 668829 ns/op 226 B/op 7 allocs/op
132BenchmarkSetRedigo100Conns1MB-4 2000 679542 ns/op 226 B/op 7 allocs/op
133```
134
135Redis Cluster:
136
137```
138BenchmarkRedisPing-4 200000 6983 ns/op 116 B/op 4 allocs/op
139BenchmarkRedisClusterPing-4 100000 11535 ns/op 117 B/op 4 allocs/op
140```
141
142## See also
143
144- [Golang PostgreSQL ORM](https://github.com/go-pg/pg)
145- [Golang msgpack](https://github.com/vmihailenco/msgpack)
146- [Golang message task queue](https://github.com/vmihailenco/taskq)
View as plain text