Type-safe Redis client for Golang
Go to file
ofekshenawa 323f8eff85
Merge branch 'master' into connection_issue
2024-12-05 10:12:08 +02:00
.github chore(deps): bump codecov/codecov-action from 4 to 5 (#3196) 2024-12-05 10:11:12 +02:00
doctests DOC-4345 added JSON samples for home page (#3183) 2024-11-06 17:25:46 +02:00
example Updated package version (#3158) 2024-10-15 16:32:53 +03:00
extra Updated package version (#3158) 2024-10-15 16:32:53 +03:00
fuzz chore: update import path 2023-01-23 08:48:54 +02:00
internal Remove direct read from TLS underlying conn (#3138) 2024-10-07 12:23:11 +03:00
scripts Release/v9.5.3 (#3018) 2024-06-07 17:04:08 +03:00
.gitignore Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
.golangci.yml chore: don't enable all lints 2021-11-19 17:09:58 +02:00
.prettierrc.yml chore: lazy reload when moved or ask 2021-10-04 13:16:33 +03:00
CHANGELOG.md Remove skipping span creation by checking parent spans (#2980) 2024-05-10 09:52:32 +03:00
CONTRIBUTING.md CONTRIBUTING guideliens (#2718) 2023-09-20 10:42:45 +03:00
LICENSE chore: update import path 2023-01-23 08:48:54 +02:00
Makefile Add test coverage reporting and Codecov badge (#3055) 2024-09-03 17:09:47 +03:00
README.md Add guidance on unstable RESP3 support for RediSearch commands to README (#3177) 2024-11-13 13:20:59 +02:00
RELEASING.md Fix releasing.md 2021-09-03 12:20:59 +03:00
acl_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
bench_decode_test.go Execute "COMMAND" command only when readonly (#2815) 2023-12-17 15:21:01 +02:00
bench_test.go chore: update import path 2023-01-23 08:48:54 +02:00
bitmap_commands.go Adding BitfieldRo in BitMapCmdable interface (#2962) 2024-04-22 01:22:00 +08:00
bitmap_commands_test.go Add support for specifying bitcount unit as byte or bit, byte default (#2887) 2024-02-14 22:15:30 +02:00
cluster_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
command.go Recognize byte slice for key argument in cluster client hash slot computation (#3049) 2024-11-21 14:38:11 +02:00
command_test.go chore: fewer test dependencies 2023-01-27 15:01:50 +00:00
commands.go RediSearch Support (#2801) 2024-06-26 13:13:06 +03:00
commands_test.go Support Hash-field expiration commands in Pipeline & Fix HExpire HExpireWithArgs expiration (#3038) 2024-07-11 13:08:23 +08:00
doc.go doc: fix outdated reference. 2014-10-07 09:27:55 +03:00
error.go fix: Fixed issue with context cancelled error leading to connection spikes on Master 2024-11-22 14:30:35 -08:00
example_instrumentation_test.go chore: update import path 2023-01-23 08:48:54 +02:00
example_test.go Fix typo in comment (#2972) 2024-04-17 00:02:39 +08:00
export_test.go Add support for MODULE LOADEX command (#2490) 2023-04-18 21:03:47 +08:00
gears_commands.go refactor(gears): remove redundant nil check (#2728) 2023-09-27 10:50:05 +03:00
gears_commands_test.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
generic_commands.go feat: add object fraq command (#2844) 2024-02-14 23:05:05 +02:00
geo_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
go.mod Fix Flaky Test: should handle FTAggregate with Unstable RESP3 Search Module and without stability (#3135) 2024-09-26 13:11:59 +03:00
go.sum chore(deps): bump github.com/bsm/ginkgo/v2 from 2.9.5 to 2.12.0 (#2690) 2023-09-20 14:57:47 +03:00
hash_commands.go Support Hash-field expiration commands in Pipeline & Fix HExpire HExpireWithArgs expiration (#3038) 2024-07-11 13:08:23 +08:00
hyperloglog_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
internal_test.go chore: fewer test dependencies 2023-01-27 15:01:50 +00:00
iterator.go fix: remove iterator mutex as it's not needed 2022-08-13 11:05:04 +10:00
iterator_test.go remove tests from RE (#3035) 2024-06-20 02:25:49 +03:00
json.go Support Json with Resp 2 (#3146) 2024-10-14 14:37:22 +03:00
json_test.go Support Json with Resp 2 (#3146) 2024-10-14 14:37:22 +03:00
list_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
main_test.go Add RE tests (#2847) 2024-01-01 22:19:22 +02:00
monitor_test.go Change monitor test to run manually (#3041) 2024-07-02 16:10:30 +03:00
options.go Support Resp 3 Redis Search Unstable Mode (#3098) 2024-09-12 11:26:10 +03:00
options_test.go Format code and fix go vet (#2696) 2023-09-20 14:03:44 +03:00
osscluster.go fix: Fixed issue with context cancelled error leading to connection spikes on Master 2024-11-22 14:30:35 -08:00
osscluster_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
osscluster_test.go Recognize byte slice for key argument in cluster client hash slot computation (#3049) 2024-11-21 14:38:11 +02:00
pipeline.go feat: check pipeline.Do to prevent confusion with Exec (#2517) 2023-04-01 14:44:06 +08:00
pipeline_test.go Add RE tests (#2847) 2024-01-01 22:19:22 +02:00
pool_test.go chore: fewer test dependencies 2023-01-27 15:01:50 +00:00
probabilistic.go Support Probabilistic commands with RESP 2 protocol (#3176) 2024-11-13 11:15:19 +02:00
probabilistic_test.go Support Probabilistic commands with RESP 2 protocol (#3176) 2024-11-13 11:15:19 +02:00
pubsub.go Update pubsub.go (#3042) 2024-07-05 10:27:44 +08:00
pubsub_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
pubsub_test.go chore: fewer test dependencies 2023-01-27 15:01:50 +00:00
race_test.go Add RE tests (#2847) 2024-01-01 22:19:22 +02:00
redis.go Eliminate redundant dial mutex causing unbounded connection queue contention (#3088) 2024-11-20 13:38:06 +02:00
redis_test.go Eliminate redundant dial mutex causing unbounded connection queue contention (#3088) 2024-11-20 13:38:06 +02:00
result.go chore: fix typo in the result.go (#2558) 2023-04-25 23:06:09 +08:00
ring.go Support Resp 3 Redis Search Unstable Mode (#3098) 2024-09-12 11:26:10 +03:00
ring_test.go feat: add protocol option (#2598) 2023-05-16 22:02:22 +08:00
script.go feat: add HasErrorPrefix 2022-11-17 16:18:04 +02:00
scripting_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
search_commands.go SortByWithCount FTSearchOptions fix (#3201) 2024-12-05 10:10:04 +02:00
search_test.go SortByWithCount FTSearchOptions fix (#3201) 2024-12-05 10:10:04 +02:00
sentinel.go Support Resp 3 Redis Search Unstable Mode (#3098) 2024-09-12 11:26:10 +03:00
sentinel_test.go Speed up connections by sending SetInfo via a pipeline (#2880) 2024-02-15 12:48:56 +02:00
set_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
sortedset_commands.go Change Z Member type to interface (#2861) 2024-01-07 11:57:20 +02:00
stream_commands.go Add support for XREAD last entry (#3005) 2024-06-20 11:25:51 +03:00
string_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
timeseries_commands.go TimeSeries insertion filters for close samples (#3003) 2024-07-11 11:57:56 +03:00
timeseries_commands_test.go Support TimeSeries commands with RESP 2 protocol (#3184) 2024-11-13 10:27:00 +02:00
tx.go chore: update import path 2023-01-23 08:48:54 +02:00
tx_test.go Add RE tests (#2847) 2024-01-01 22:19:22 +02:00
universal.go Support Resp 3 Redis Search Unstable Mode (#3098) 2024-09-12 11:26:10 +03:00
universal_test.go Add RE tests (#2847) 2024-01-01 22:19:22 +02:00
version.go Updated package version (#3158) 2024-10-15 16:32:53 +03:00

README.md

Redis client for Go

build workflow PkgGoDev Documentation codecov Chat

go-redis is brought to you by uptrace/uptrace. Uptrace is an open-source APM tool that supports distributed tracing, metrics, and logs. You can use it to monitor applications and set up automatic alerts to receive notifications via email, Slack, Telegram, and others.

See OpenTelemetry example which demonstrates how you can use Uptrace to monitor go-redis.

How do I Redis?

Learn for free at Redis University

Build faster with the Redis Launchpad

Try the Redis Cloud

Dive in developer tutorials

Join the Redis community

Work at Redis

Documentation

Resources

Ecosystem

This client also works with Kvrocks, a distributed key value NoSQL database that uses RocksDB as storage engine and is compatible with Redis protocol.

Features

Installation

go-redis supports 2 last Go versions and requires a Go version with modules support. So make sure to initialize a Go module:

go mod init github.com/my/repo

Then install go-redis/v9:

go get github.com/redis/go-redis/v9

Quickstart

import (
    "context"
    "fmt"

    "github.com/redis/go-redis/v9"
)

var ctx = context.Background()

func ExampleClient() {
    rdb := redis.NewClient(&redis.Options{
        Addr:     "localhost:6379",
        Password: "", // no password set
        DB:       0,  // use default DB
    })

    err := rdb.Set(ctx, "key", "value", 0).Err()
    if err != nil {
        panic(err)
    }

    val, err := rdb.Get(ctx, "key").Result()
    if err != nil {
        panic(err)
    }
    fmt.Println("key", val)

    val2, err := rdb.Get(ctx, "key2").Result()
    if err == redis.Nil {
        fmt.Println("key2 does not exist")
    } else if err != nil {
        panic(err)
    } else {
        fmt.Println("key2", val2)
    }
    // Output: key value
    // key2 does not exist
}

The above can be modified to specify the version of the RESP protocol by adding the protocol option to the Options struct:

    rdb := redis.NewClient(&redis.Options{
        Addr:     "localhost:6379",
        Password: "", // no password set
        DB:       0,  // use default DB
        Protocol: 3, // specify 2 for RESP 2 or 3 for RESP 3
    })

Connecting via a redis url

go-redis also supports connecting via the redis uri specification. The example below demonstrates how the connection can easily be configured using a string, adhering to this specification.

import (
    "github.com/redis/go-redis/v9"
)

func ExampleClient() *redis.Client {
    url := "redis://user:password@localhost:6379/0?protocol=3"
    opts, err := redis.ParseURL(url)
    if err != nil {
        panic(err)
    }

    return redis.NewClient(opts)
}

Advanced Configuration

go-redis supports extending the client identification phase to allow projects to send their own custom client identification.

Default Client Identification

By 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.

Disabling Identity Verification

When connection identity verification is not required or needs to be explicitly disabled, a DisableIndentity configuration option exists. In V10 of this library, DisableIndentity will become DisableIdentity in order to fix the associated typo.

To disable verification, set the DisableIndentity option to true in the Redis client options:

rdb := redis.NewClient(&redis.Options{
    Addr:            "localhost:6379",
    Password:        "",
    DB:              0,
    DisableIndentity: true, // Disable set-info on connect
})

Unstable RESP3 Structures for RediSearch Commands

When 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.

To enable unstable RESP3, set the option in your client configuration:

redis.NewClient(&redis.Options{
			UnstableResp3: true,
		})

Note: When UnstableResp3 mode is enabled, it's necessary to use RawResult() and RawVal() to retrieve a raw data. Since, raw response is the only option for unstable search commands Val() and Result() calls wouldn't have any affect on them:

res1, err := client.FTSearchWithArgs(ctx, "txt", "foo bar", &redis.FTSearchOptions{}).RawResult()
val1 := client.FTSearchWithArgs(ctx, "txt", "foo bar", &redis.FTSearchOptions{}).RawVal()

Contributing

Please see out contributing guidelines to help us improve this library!

Look and feel

Some corner cases:

// SET key value EX 10 NX
set, err := rdb.SetNX(ctx, "key", "value", 10*time.Second).Result()

// SET key value keepttl NX
set, err := rdb.SetNX(ctx, "key", "value", redis.KeepTTL).Result()

// SORT list LIMIT 0 2 ASC
vals, err := rdb.Sort(ctx, "list", &redis.Sort{Offset: 0, Count: 2, Order: "ASC"}).Result()

// ZRANGEBYSCORE zset -inf +inf WITHSCORES LIMIT 0 2
vals, err := rdb.ZRangeByScoreWithScores(ctx, "zset", &redis.ZRangeBy{
    Min: "-inf",
    Max: "+inf",
    Offset: 0,
    Count: 2,
}).Result()

// ZINTERSTORE out 2 zset1 zset2 WEIGHTS 2 3 AGGREGATE SUM
vals, err := rdb.ZInterStore(ctx, "out", &redis.ZStore{
    Keys: []string{"zset1", "zset2"},
    Weights: []int64{2, 3}
}).Result()

// EVAL "return {KEYS[1],ARGV[1]}" 1 "key" "hello"
vals, err := rdb.Eval(ctx, "return {KEYS[1],ARGV[1]}", []string{"key"}, "hello").Result()

// custom command
res, err := rdb.Do(ctx, "set", "key", "value").Result()

Run the test

go-redis will start a redis-server and run the test cases.

The paths of redis-server bin file and redis config file are defined in main_test.go:

var (
	redisServerBin, _  = filepath.Abs(filepath.Join("testdata", "redis", "src", "redis-server"))
	redisServerConf, _ = filepath.Abs(filepath.Join("testdata", "redis", "redis.conf"))
)

For local testing, you can change the variables to refer to your local files, or create a soft link to the corresponding folder for redis-server and copy the config file to testdata/redis/:

ln -s /usr/bin/redis-server ./go-redis/testdata/redis/src
cp ./go-redis/testdata/redis.conf ./go-redis/testdata/redis/

Lastly, run:

go test

Another option is to run your specific tests with an already running redis. The example below, tests against a redis running on port 9999.:

REDIS_PORT=9999 go test <your options>

See also

Contributors

Thanks to all the people who already contributed!