1# Redis client for Go
2
3[](https://github.com/redis/go-redis/actions)
4[](https://pkg.go.dev/github.com/redis/go-redis/v9?tab=doc)
5[](https://redis.uptrace.dev/)
6[](https://goreportcard.com/report/github.com/redis/go-redis/v9)
7[](https://codecov.io/github/redis/go-redis)
8
9[](https://discord.gg/W4txy5AeKM)
10[](https://www.twitch.tv/redisinc)
11[](https://www.youtube.com/redisinc)
12[](https://twitter.com/redisinc)
13[](https://stackoverflow.com/questions/tagged/go-redis)
14
15> go-redis is the official Redis client library for the Go programming language. It offers a straightforward interface for interacting with Redis servers.
16
17## Supported versions
18
19In `go-redis` we are aiming to support the last three releases of Redis. Currently, this means we do support:
20- [Redis 7.2](https://raw.githubusercontent.com/redis/redis/7.2/00-RELEASENOTES) - using Redis Stack 7.2 for modules support
21- [Redis 7.4](https://raw.githubusercontent.com/redis/redis/7.4/00-RELEASENOTES) - using Redis Stack 7.4 for modules support
22- [Redis 8.0](https://raw.githubusercontent.com/redis/redis/8.0/00-RELEASENOTES) - using Redis CE 8.0 where modules are included
23- [Redis 8.2](https://raw.githubusercontent.com/redis/redis/8.2/00-RELEASENOTES) - using Redis CE 8.2 where modules are included
24
25Although the `go.mod` states it requires at minimum `go 1.18`, our CI is configured to run the tests against all three
26versions of Redis and latest two versions of Go ([1.23](https://go.dev/doc/devel/release#go1.23.0),
27[1.24](https://go.dev/doc/devel/release#go1.24.0)). We observe that some modules related test may not pass with
28Redis Stack 7.2 and some commands are changed with Redis CE 8.0.
29Please do refer to the documentation and the tests if you experience any issues. We do plan to update the go version
30in the `go.mod` to `go 1.24` in one of the next releases.
31
32## How do I Redis?
33
34[Learn for free at Redis University](https://university.redis.com/)
35
36[Build faster with the Redis Launchpad](https://launchpad.redis.com/)
37
38[Try the Redis Cloud](https://redis.com/try-free/)
39
40[Dive in developer tutorials](https://developer.redis.com/)
41
42[Join the Redis community](https://redis.com/community/)
43
44[Work at Redis](https://redis.com/company/careers/jobs/)
45
46## Documentation
47
48- [English](https://redis.uptrace.dev)
49- [简体中文](https://redis.uptrace.dev/zh/)
50
51## Resources
52
53- [Discussions](https://github.com/redis/go-redis/discussions)
54- [Chat](https://discord.gg/W4txy5AeKM)
55- [Reference](https://pkg.go.dev/github.com/redis/go-redis/v9)
56- [Examples](https://pkg.go.dev/github.com/redis/go-redis/v9#pkg-examples)
57
58## Ecosystem
59
60- [Redis Mock](https://github.com/go-redis/redismock)
61- [Distributed Locks](https://github.com/bsm/redislock)
62- [Redis Cache](https://github.com/go-redis/cache)
63- [Rate limiting](https://github.com/go-redis/redis_rate)
64
65This client also works with [Kvrocks](https://github.com/apache/incubator-kvrocks), a distributed
66key value NoSQL database that uses RocksDB as storage engine and is compatible with Redis protocol.
67
68## Features
69
70- Redis commands except QUIT and SYNC.
71- Automatic connection pooling.
72- [StreamingCredentialsProvider (e.g. entra id, oauth)](#1-streaming-credentials-provider-highest-priority) (experimental)
73- [Pub/Sub](https://redis.uptrace.dev/guide/go-redis-pubsub.html).
74- [Pipelines and transactions](https://redis.uptrace.dev/guide/go-redis-pipelines.html).
75- [Scripting](https://redis.uptrace.dev/guide/lua-scripting.html).
76- [Redis Sentinel](https://redis.uptrace.dev/guide/go-redis-sentinel.html).
77- [Redis Cluster](https://redis.uptrace.dev/guide/go-redis-cluster.html).
78- [Redis Ring](https://redis.uptrace.dev/guide/ring.html).
79- [Redis Performance Monitoring](https://redis.uptrace.dev/guide/redis-performance-monitoring.html).
80- [Redis Probabilistic [RedisStack]](https://redis.io/docs/data-types/probabilistic/)
81- [Customizable read and write buffers size.](#custom-buffer-sizes)
82
83## Installation
84
85go-redis supports 2 last Go versions and requires a Go version with
86[modules](https://github.com/golang/go/wiki/Modules) support. So make sure to initialize a Go
87module:
88
89```shell
90go mod init github.com/my/repo
91```
92
93Then install go-redis/**v9**:
94
95```shell
96go get github.com/redis/go-redis/v9
97```
98
99## Quickstart
100
101```go
102import (
103 "context"
104 "fmt"
105
106 "github.com/redis/go-redis/v9"
107)
108
109var ctx = context.Background()
110
111func ExampleClient() {
112 rdb := redis.NewClient(&redis.Options{
113 Addr: "localhost:6379",
114 Password: "", // no password set
115 DB: 0, // use default DB
116 })
117
118 err := rdb.Set(ctx, "key", "value", 0).Err()
119 if err != nil {
120 panic(err)
121 }
122
123 val, err := rdb.Get(ctx, "key").Result()
124 if err != nil {
125 panic(err)
126 }
127 fmt.Println("key", val)
128
129 val2, err := rdb.Get(ctx, "key2").Result()
130 if err == redis.Nil {
131 fmt.Println("key2 does not exist")
132 } else if err != nil {
133 panic(err)
134 } else {
135 fmt.Println("key2", val2)
136 }
137 // Output: key value
138 // key2 does not exist
139}
140```
141
142### Authentication
143
144The Redis client supports multiple ways to provide authentication credentials, with a clear priority order. Here are the available options:
145
146#### 1. Streaming Credentials Provider (Highest Priority) - Experimental feature
147
148The streaming credentials provider allows for dynamic credential updates during the connection lifetime. This is particularly useful for managed identity services and token-based authentication.
149
150```go
151type StreamingCredentialsProvider interface {
152 Subscribe(listener CredentialsListener) (Credentials, UnsubscribeFunc, error)
153}
154
155type CredentialsListener interface {
156 OnNext(credentials Credentials) // Called when credentials are updated
157 OnError(err error) // Called when an error occurs
158}
159
160type Credentials interface {
161 BasicAuth() (username string, password string)
162 RawCredentials() string
163}
164```
165
166Example usage:
167```go
168rdb := redis.NewClient(&redis.Options{
169 Addr: "localhost:6379",
170 StreamingCredentialsProvider: &MyCredentialsProvider{},
171})
172```
173
174**Note:** The streaming credentials provider can be used with [go-redis-entraid](https://github.com/redis/go-redis-entraid) to enable Entra ID (formerly Azure AD) authentication. This allows for seamless integration with Azure's managed identity services and token-based authentication.
175
176Example with Entra ID:
177```go
178import (
179 "github.com/redis/go-redis/v9"
180 "github.com/redis/go-redis-entraid"
181)
182
183// Create an Entra ID credentials provider
184provider := entraid.NewDefaultAzureIdentityProvider()
185
186// Configure Redis client with Entra ID authentication
187rdb := redis.NewClient(&redis.Options{
188 Addr: "your-redis-server.redis.cache.windows.net:6380",
189 StreamingCredentialsProvider: provider,
190 TLSConfig: &tls.Config{
191 MinVersion: tls.VersionTLS12,
192 },
193})
194```
195
196#### 2. Context-based Credentials Provider
197
198The context-based provider allows credentials to be determined at the time of each operation, using the context.
199
200```go
201rdb := redis.NewClient(&redis.Options{
202 Addr: "localhost:6379",
203 CredentialsProviderContext: func(ctx context.Context) (string, string, error) {
204 // Return username, password, and any error
205 return "user", "pass", nil
206 },
207})
208```
209
210#### 3. Regular Credentials Provider
211
212A simple function-based provider that returns static credentials.
213
214```go
215rdb := redis.NewClient(&redis.Options{
216 Addr: "localhost:6379",
217 CredentialsProvider: func() (string, string) {
218 // Return username and password
219 return "user", "pass"
220 },
221})
222```
223
224#### 4. Username/Password Fields (Lowest Priority)
225
226The most basic way to provide credentials is through the `Username` and `Password` fields in the options.
227
228```go
229rdb := redis.NewClient(&redis.Options{
230 Addr: "localhost:6379",
231 Username: "user",
232 Password: "pass",
233})
234```
235
236#### Priority Order
237
238The client will use credentials in the following priority order:
2391. Streaming Credentials Provider (if set)
2402. Context-based Credentials Provider (if set)
2413. Regular Credentials Provider (if set)
2424. Username/Password fields (if set)
243
244If none of these are set, the client will attempt to connect without authentication.
245
246### Protocol Version
247
248The client supports both RESP2 and RESP3 protocols. You can specify the protocol version in the options:
249
250```go
251rdb := redis.NewClient(&redis.Options{
252 Addr: "localhost:6379",
253 Password: "", // no password set
254 DB: 0, // use default DB
255 Protocol: 3, // specify 2 for RESP 2 or 3 for RESP 3
256})
257```
258
259### Connecting via a redis url
260
261go-redis also supports connecting via the
262[redis uri specification](https://github.com/redis/redis-specifications/tree/master/uri/redis.txt).
263The example below demonstrates how the connection can easily be configured using a string, adhering
264to this specification.
265
266```go
267import (
268 "github.com/redis/go-redis/v9"
269)
270
271func ExampleClient() *redis.Client {
272 url := "redis://user:password@localhost:6379/0?protocol=3"
273 opts, err := redis.ParseURL(url)
274 if err != nil {
275 panic(err)
276 }
277
278 return redis.NewClient(opts)
279}
280
281```
282
283### Instrument with OpenTelemetry
284
285```go
286import (
287 "github.com/redis/go-redis/v9"
288 "github.com/redis/go-redis/extra/redisotel/v9"
289 "errors"
290)
291
292func main() {
293 ...
294 rdb := redis.NewClient(&redis.Options{...})
295
296 if err := errors.Join(redisotel.InstrumentTracing(rdb), redisotel.InstrumentMetrics(rdb)); err != nil {
297 log.Fatal(err)
298 }
299```
300
301
302### Buffer Size Configuration
303
304go-redis uses 32KiB read and write buffers by default for optimal performance. For high-throughput applications or large pipelines, you can customize buffer sizes:
305
306```go
307rdb := redis.NewClient(&redis.Options{
308 Addr: "localhost:6379",
309 ReadBufferSize: 1024 * 1024, // 1MiB read buffer
310 WriteBufferSize: 1024 * 1024, // 1MiB write buffer
311})
312```
313
314### Advanced Configuration
315
316go-redis supports extending the client identification phase to allow projects to send their own custom client identification.
317
318#### Default Client Identification
319
320By 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.
321
322#### Disabling Identity Verification
323
324When connection identity verification is not required or needs to be explicitly disabled, a `DisableIdentity` configuration option exists.
325Initially there was a typo and the option was named `DisableIndentity` instead of `DisableIdentity`. The misspelled option is marked as Deprecated and will be removed in V10 of this library.
326Although both options will work at the moment, the correct option is `DisableIdentity`. The deprecated option will be removed in V10 of this library, so please use the correct option name to avoid any issues.
327
328To disable verification, set the `DisableIdentity` option to `true` in the Redis client options:
329
330```go
331rdb := redis.NewClient(&redis.Options{
332 Addr: "localhost:6379",
333 Password: "",
334 DB: 0,
335 DisableIdentity: true, // Disable set-info on connect
336})
337```
338
339#### Unstable RESP3 Structures for RediSearch Commands
340When integrating Redis with application functionalities using RESP3, it's important to note that some response structures aren't final yet. This is especially true for more complex structures like search and query results. We recommend using RESP2 when using the search and query capabilities, but we plan to stabilize the RESP3-based API-s in the coming versions. You can find more guidance in the upcoming release notes.
341
342To enable unstable RESP3, set the option in your client configuration:
343
344```go
345redis.NewClient(&redis.Options{
346 UnstableResp3: true,
347 })
348```
349**Note:** When UnstableResp3 mode is enabled, it's necessary to use RawResult() and RawVal() to retrieve a raw data.
350 Since, raw response is the only option for unstable search commands Val() and Result() calls wouldn't have any affect on them:
351
352```go
353res1, err := client.FTSearchWithArgs(ctx, "txt", "foo bar", &redis.FTSearchOptions{}).RawResult()
354val1 := client.FTSearchWithArgs(ctx, "txt", "foo bar", &redis.FTSearchOptions{}).RawVal()
355```
356
357#### Redis-Search Default Dialect
358
359In the Redis-Search module, **the default dialect is 2**. If needed, you can explicitly specify a different dialect using the appropriate configuration in your queries.
360
361**Important**: Be aware that the query dialect may impact the results returned. If needed, you can revert to a different dialect version by passing the desired dialect in the arguments of the command you want to execute.
362For example:
363```
364 res2, err := rdb.FTSearchWithArgs(ctx,
365 "idx:bicycle",
366 "@pickup_zone:[CONTAINS $bike]",
367 &redis.FTSearchOptions{
368 Params: map[string]interface{}{
369 "bike": "POINT(-0.1278 51.5074)",
370 },
371 DialectVersion: 3,
372 },
373 ).Result()
374```
375You can find further details in the [query dialect documentation](https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/dialects/).
376
377#### Custom buffer sizes
378Prior to v9.12, the buffer size was the default go value of 4096 bytes. Starting from v9.12,
379go-redis uses 32KiB read and write buffers by default for optimal performance.
380For high-throughput applications or large pipelines, you can customize buffer sizes:
381
382```go
383rdb := redis.NewClient(&redis.Options{
384 Addr: "localhost:6379",
385 ReadBufferSize: 1024 * 1024, // 1MiB read buffer
386 WriteBufferSize: 1024 * 1024, // 1MiB write buffer
387})
388```
389
390**Important**: If you experience any issues with the default buffer sizes, please try setting them to the go default of 4096 bytes.
391
392## Contributing
393We welcome contributions to the go-redis library! If you have a bug fix, feature request, or improvement, please open an issue or pull request on GitHub.
394We appreciate your help in making go-redis better for everyone.
395If you are interested in contributing to the go-redis library, please check out our [contributing guidelines](CONTRIBUTING.md) for more information on how to get started.
396
397## Look and feel
398
399Some corner cases:
400
401```go
402// SET key value EX 10 NX
403set, err := rdb.SetNX(ctx, "key", "value", 10*time.Second).Result()
404
405// SET key value keepttl NX
406set, err := rdb.SetNX(ctx, "key", "value", redis.KeepTTL).Result()
407
408// SORT list LIMIT 0 2 ASC
409vals, err := rdb.Sort(ctx, "list", &redis.Sort{Offset: 0, Count: 2, Order: "ASC"}).Result()
410
411// ZRANGEBYSCORE zset -inf +inf WITHSCORES LIMIT 0 2
412vals, err := rdb.ZRangeByScoreWithScores(ctx, "zset", &redis.ZRangeBy{
413 Min: "-inf",
414 Max: "+inf",
415 Offset: 0,
416 Count: 2,
417}).Result()
418
419// ZINTERSTORE out 2 zset1 zset2 WEIGHTS 2 3 AGGREGATE SUM
420vals, err := rdb.ZInterStore(ctx, "out", &redis.ZStore{
421 Keys: []string{"zset1", "zset2"},
422 Weights: []int64{2, 3}
423}).Result()
424
425// EVAL "return {KEYS[1],ARGV[1]}" 1 "key" "hello"
426vals, err := rdb.Eval(ctx, "return {KEYS[1],ARGV[1]}", []string{"key"}, "hello").Result()
427
428// custom command
429res, err := rdb.Do(ctx, "set", "key", "value").Result()
430```
431
432
433## Run the test
434
435Recommended to use Docker, just need to run:
436```shell
437make test
438```
439
440## See also
441
442- [Golang ORM](https://bun.uptrace.dev) for PostgreSQL, MySQL, MSSQL, and SQLite
443- [Golang PostgreSQL](https://bun.uptrace.dev/postgres/)
444- [Golang HTTP router](https://bunrouter.uptrace.dev/)
445- [Golang ClickHouse ORM](https://github.com/uptrace/go-clickhouse)
446
447## Contributors
448
449> The go-redis project was originally initiated by :star: [**uptrace/uptrace**](https://github.com/uptrace/uptrace).
450> Uptrace is an open-source APM tool that supports distributed tracing, metrics, and logs. You can
451> use it to monitor applications and set up automatic alerts to receive notifications via email,
452> Slack, Telegram, and others.
453>
454> See [OpenTelemetry](https://github.com/redis/go-redis/tree/master/example/otel) example which
455> demonstrates how you can use Uptrace to monitor go-redis.
456
457Thanks to all the people who already contributed!
458
459<a href="https://github.com/redis/go-redis/graphs/contributors">
460 <img src="https://contributors-img.web.app/image?repo=redis/go-redis" />
461</a>
View as plain text