1<p align="center"> 2 <a href="https://uptrace.dev/?utm_source=gh-redis&utm_campaign=gh-redis-banner1"> 3 <img src="https://raw.githubusercontent.com/uptrace/roadmap/master/banner1.png" alt="All-in-one tool to optimize performance and monitor errors & logs"> 4 </a> 5</p> 6 7# Redis client for Golang 8 9![build workflow](https://github.com/go-redis/redis/actions/workflows/build.yml/badge.svg) 10[![PkgGoDev](https://pkg.go.dev/badge/github.com/go-redis/redis/v8)](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc) 11[![Documentation](https://img.shields.io/badge/redis-documentation-informational)](https://redis.uptrace.dev/) 12[![Chat](https://discordapp.com/api/guilds/752070105847955518/widget.png)](https://discord.gg/rWtp5Aj) 13 14- Join [Discord](https://discord.gg/rWtp5Aj) to ask questions. 15- [Documentation](https://redis.uptrace.dev) 16- [Reference](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc) 17- [Examples](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc#pkg-examples) 18- [RealWorld example app](https://github.com/uptrace/go-treemux-realworld-example-app) 19 20## Ecosystem 21 22- [Redis Mock](https://github.com/go-redis/redismock). 23- [Distributed Locks](https://github.com/bsm/redislock). 24- [Redis Cache](https://github.com/go-redis/cache). 25- [Rate limiting](https://github.com/go-redis/redis_rate). 26 27## Features 28 29- Redis 3 commands except QUIT, MONITOR, and SYNC. 30- Automatic connection pooling with 31 [circuit breaker](https://en.wikipedia.org/wiki/Circuit_breaker_design_pattern) support. 32- [Pub/Sub](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc#PubSub). 33- [Transactions](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc#example-Client-TxPipeline). 34- [Pipeline](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc#example-Client-Pipeline) and 35 [TxPipeline](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc#example-Client-TxPipeline). 36- [Scripting](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc#Script). 37- [Timeouts](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc#Options). 38- [Redis Sentinel](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc#NewFailoverClient). 39- [Redis Cluster](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc#NewClusterClient). 40- [Cluster of Redis Servers](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc#example-NewClusterClient--ManualSetup) 41 without using cluster mode and Redis Sentinel. 42- [Ring](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc#NewRing). 43- [Instrumentation](https://pkg.go.dev/github.com/go-redis/redis/v8?tab=doc#ex-package--Instrumentation). 44 45## Installation 46 47go-redis supports 2 last Go versions and requires a Go version with 48[modules](https://github.com/golang/go/wiki/Modules) support. So make sure to initialize a Go 49module: 50 51```shell 52go mod init github.com/my/repo 53``` 54 55And then install go-redis/v8 (note _v8_ in the import; omitting it is a popular mistake): 56 57```shell 58go get github.com/go-redis/redis/v8 59``` 60 61## Quickstart 62 63```go 64import ( 65 "context" 66 "github.com/go-redis/redis/v8" 67) 68 69var ctx = context.Background() 70 71func ExampleClient() { 72 rdb := redis.NewClient(&redis.Options{ 73 Addr: "localhost:6379", 74 Password: "", // no password set 75 DB: 0, // use default DB 76 }) 77 78 err := rdb.Set(ctx, "key", "value", 0).Err() 79 if err != nil { 80 panic(err) 81 } 82 83 val, err := rdb.Get(ctx, "key").Result() 84 if err != nil { 85 panic(err) 86 } 87 fmt.Println("key", val) 88 89 val2, err := rdb.Get(ctx, "key2").Result() 90 if err == redis.Nil { 91 fmt.Println("key2 does not exist") 92 } else if err != nil { 93 panic(err) 94 } else { 95 fmt.Println("key2", val2) 96 } 97 // Output: key value 98 // key2 does not exist 99} 100``` 101 102## Look and feel 103 104Some corner cases: 105 106```go 107// SET key value EX 10 NX 108set, err := rdb.SetNX(ctx, "key", "value", 10*time.Second).Result() 109 110// SET key value keepttl NX 111set, err := rdb.SetNX(ctx, "key", "value", redis.KeepTTL).Result() 112 113// SORT list LIMIT 0 2 ASC 114vals, err := rdb.Sort(ctx, "list", &redis.Sort{Offset: 0, Count: 2, Order: "ASC"}).Result() 115 116// ZRANGEBYSCORE zset -inf +inf WITHSCORES LIMIT 0 2 117vals, err := rdb.ZRangeByScoreWithScores(ctx, "zset", &redis.ZRangeBy{ 118 Min: "-inf", 119 Max: "+inf", 120 Offset: 0, 121 Count: 2, 122}).Result() 123 124// ZINTERSTORE out 2 zset1 zset2 WEIGHTS 2 3 AGGREGATE SUM 125vals, err := rdb.ZInterStore(ctx, "out", &redis.ZStore{ 126 Keys: []string{"zset1", "zset2"}, 127 Weights: []int64{2, 3} 128}).Result() 129 130// EVAL "return {KEYS[1],ARGV[1]}" 1 "key" "hello" 131vals, err := rdb.Eval(ctx, "return {KEYS[1],ARGV[1]}", []string{"key"}, "hello").Result() 132 133// custom command 134res, err := rdb.Do(ctx, "set", "key", "value").Result() 135``` 136 137## Run the test 138 139go-redis will start a redis-server and run the test cases. 140 141The paths of redis-server bin file and redis config file are defined in `main_test.go`: 142 143``` 144var ( 145 redisServerBin, _ = filepath.Abs(filepath.Join("testdata", "redis", "src", "redis-server")) 146 redisServerConf, _ = filepath.Abs(filepath.Join("testdata", "redis", "redis.conf")) 147) 148``` 149 150For local testing, you can change the variables to refer to your local files, or create a soft link 151to the corresponding folder for redis-server and copy the config file to `testdata/redis/`: 152 153``` 154ln -s /usr/bin/redis-server ./go-redis/testdata/redis/src 155cp ./go-redis/testdata/redis.conf ./go-redis/testdata/redis/ 156``` 157 158Lastly, run: 159 160``` 161go test 162``` 163 164## See also 165 166- [Fast and flexible ORM](https://github.com/uptrace/bun) 167- [msgpack for Go](https://github.com/vmihailenco/msgpack) 168