1# Redis client for Golang
2
3[![Build Status](https://travis-ci.org/go-redis/redis.png?branch=master)](https://travis-ci.org/go-redis/redis)
4[![GoDoc](https://godoc.org/github.com/go-redis/redis?status.svg)](https://godoc.org/github.com/go-redis/redis)
5[![Airbrake](https://img.shields.io/badge/kudos-airbrake.io-orange.svg)](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