Type-safe Redis client for Golang
Go to file
ofekshenawa 0d7a013e5d
Json support (#2769)
* Add support for RedisJSON

* Add optional args and tests

* Add more tests

* Add more tests

* Add more tests and cleanups

* Add docstring

* update JSONArrIndex and matching texts

Rename JSONArrIndexWithArgs to JSONArrIndexArgs
change name of args struct to match function name for consistency
change arg types to int (for required arg) and *int (for optional)

* update JSONArrTrim and matching texts

Rename JSONArrTrimWithArgs to JSONArrTrimArgs
change name of args struct to match function name for consistency
change arg types to int (for required arg) and *int (for optional)

* update JSONGetWithArgs and matching texts

Rename JSONGetWithArgs to JSONGetArgs
Removed Paths & Path from args - redundant and ambiguous
Renamed mispelled "Indention"
Changed args param from pointer to value
Updated and added additional tests for formatting params

* Update JSONSetMode

changed mode parameter back to string, added value checking for that
string

* Updated JSONMSet

Changed name of param struct to ...Args  for consistency
Updated arg list to use an array of structs not pointers as
all args are mandatory (we never want to pass a nil parameter)

* Updated tests for JSONMSet

* Added stubbed (panicking) implementations of JSON.RESP AND JSON.DEBUG

* Pre-pull request tidy up

Renamed xArgs() to xWithArgs to match other Redis modules

Modified params to xWithArgs functions to use a pointer for the
arguments struct to match other Redis modules.

Modified JSONMSet to JSONMSetArgs and added a version that takes
a vararray of args to match the semantics of the native redis call

Updated tests to match above changes.

Renamed some variables in the json tests for consistency

* Testing fixes

Fixed error in JSONSetWithArgs found during tests
Fixed tests for indentation

* fix JSONCmdable typo (#5)

* Remove deprecated command: JSONNumMultBy (#6)

* Lowercase newJSONCmd (#7)

---------

Co-authored-by: Nic Gibson <nic.gibson@redis.com>
Co-authored-by: Nic Gibson <newt+github@noslogan.org>
2023-10-30 14:09:25 +02:00
.github chore(deps): bump actions/stale from 3 to 8 (#2732) 2023-09-27 11:24:47 +03:00
doctests Format code and fix go vet (#2696) 2023-09-20 14:03:44 +03:00
example Bump version to 9.2.1 (#2735) 2023-09-27 11:25:09 +03:00
extra Bump version to 9.2.1 (#2735) 2023-09-27 11:25:09 +03:00
fuzz chore: update import path 2023-01-23 08:48:54 +02:00
internal Added MaxActiveConns (#2646) 2023-09-20 14:55:23 +03:00
scripts chore: downgrade OpenTelemetry 2023-01-30 09:47:57 +02: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 chore: release v9.0.5 (release.sh) (#2614) 2023-05-29 09:05:49 +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 Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
README.md chore: use abs link 2023-10-20 08:41:48 +03: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 Identify client on connect (#2708) 2023-09-20 10:33:09 +03:00
bench_test.go chore: update import path 2023-01-23 08:48:54 +02:00
bitmap_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
cluster_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
command.go Format code and fix go vet (#2696) 2023-09-20 14:03:44 +03:00
command_test.go chore: fewer test dependencies 2023-01-27 15:01:50 +00:00
commands.go Json support (#2769) 2023-10-30 14:09:25 +02:00
commands_test.go Added the support for WAITAOF which is a new command in redis ver7.2.0 (#2629) 2023-09-20 14:09:23 +03:00
doc.go doc: fix outdated reference. 2014-10-07 09:27:55 +03:00
error.go chore: update import path 2023-01-23 08:48:54 +02:00
example_instrumentation_test.go chore: update import path 2023-01-23 08:48:54 +02:00
example_test.go doc: pass ctx in example for infinite wait time (#2540) 2023-04-06 00:16:26 +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 Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
geo_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
go.mod 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
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 Making command structs digestable (#2716) 2023-09-20 16:08:24 +03: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 chore: fewer test dependencies 2023-01-27 15:01:50 +00:00
json.go Json support (#2769) 2023-10-30 14:09:25 +02:00
json_test.go Json support (#2769) 2023-10-30 14:09:25 +02:00
list_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
main_test.go Format code and fix go vet (#2696) 2023-09-20 14:03:44 +03:00
options.go Added MaxActiveConns (#2646) 2023-09-20 14:55:23 +03:00
options_test.go Format code and fix go vet (#2696) 2023-09-20 14:03:44 +03:00
osscluster.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
osscluster_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
osscluster_test.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
package.json Bump version to 9.2.1 (#2735) 2023-09-27 11:25:09 +03:00
pipeline.go feat: check pipeline.Do to prevent confusion with Exec (#2517) 2023-04-01 14:44:06 +08:00
pipeline_test.go feat: check pipeline.Do to prevent confusion with Exec (#2517) 2023-04-01 14:44:06 +08:00
pool_test.go chore: fewer test dependencies 2023-01-27 15:01:50 +00:00
probabilistic.go make public probabilistic and redis gears interfaces (#2695) 2023-09-20 14:54:50 +03:00
probabilistic_test.go Format code and fix go vet (#2696) 2023-09-20 14:03:44 +03:00
pubsub.go chore: update import path 2023-01-23 08:48:54 +02: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 chore: fewer test dependencies 2023-01-27 15:01:50 +00:00
redis.go Identify client on connect (#2708) 2023-09-20 10:33:09 +03:00
redis_test.go feat: add protocol option (#2598) 2023-05-16 22:02:22 +08:00
result.go chore: fix typo in the result.go (#2558) 2023-04-25 23:06:09 +08:00
ring.go Format code and fix go vet (#2696) 2023-09-20 14:03:44 +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
sentinel.go feat: add protocol option (#2598) 2023-05-16 22:02:22 +08:00
sentinel_test.go Skip flaky tests (#2699) 2023-09-10 15:43:22 +03:00
set_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
sortedset_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
stream_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
string_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
timeseries_commands.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
timeseries_commands_test.go Making command structs digestable (#2716) 2023-09-20 16:08:24 +03:00
tx.go chore: update import path 2023-01-23 08:48:54 +02:00
tx_test.go chore: fewer test dependencies 2023-01-27 15:01:50 +00:00
universal.go feat: add protocol option (#2598) 2023-05-16 22:02:22 +08:00
universal_test.go Skip flaky tests (#2699) 2023-09-10 15:43:22 +03:00
version.go Bump version to 9.2.1 (#2735) 2023-09-27 11:25:09 +03:00

README.md

Redis client for Go

build workflow PkgGoDev Documentation 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.

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 (
    "context"
    "fmt"

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

var ctx = context.Background()

func ExampleClient() {
    url := "redis://localhost:6379?password=hello&protocol=3"
    opts, err := redis.ParseURL(url)
    if err != nil {
        panic(err)
    }
    rdb := redis.NewClient(opts)

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!