gopkg.in/mediocregopher/radix.v3
Package radix implements all functionality needed to work with redis and all things related to it, including redis cluster, pubsub, sentinel, scanning, lua scripting, and more. For a single node redis instance use NewPool to create a connection pool. The connection pool is thread-safe and will automatically create, reuse, and recreate connections as needed: If you're using sentinel or cluster you should use NewSentinel or NewCluster (respectively) to create your client instead. Any redis command can be performed by passing a Cmd into a Client's Do method. Each Cmd should only be used once. The return from the Cmd can be captured into any appopriate go primitive type, or a slice, map, or struct, if the command returns an array. FlatCmd can also be used if you wish to use non-string arguments like integers, slices, maps, or structs, and have them automatically be flattened into a single string slice. Cmd and FlatCmd can unmarshal results into a struct. The results must be a key/value array, such as that returned by HGETALL. Exported field names will be used as keys, unless the fields have the "redis" tag: Embedded structs will inline that struct's fields into the parent's: The same rules for field naming apply when a struct is passed into FlatCmd as an argument. Cmd and FlatCmd both implement the Action interface. Other Actions include Pipeline, WithConn, and EvalScript.Cmd. Any of these may be passed into any Client's Do method. There are two ways to perform transactions in redis. The first is with the MULTI/EXEC commands, which can be done using the WithConn Action (see its example). The second is using EVAL with lua scripting, which can be done using the EvalScript Action (again, see its example). EVAL with lua scripting is recommended in almost all cases. It only requires a single round-trip, it's infinitely more flexible than MULTI/EXEC, it's simpler to code, and for complex transactions, which would otherwise need a WATCH statement with MULTI/EXEC, it's significantly faster. All the client creation functions (e.g. NewPool) take in either a ConnFunc or a ClientFunc via their options. These can be used in order to set up timeouts on connections, perform authentication commands, or even implement custom pools. All interfaces in this package were designed such that they could have custom implementations. There is no dependency within radix that demands any interface be implemented by a particular underlying type, so feel free to create your own Pools or Conns or Actions or whatever makes your life easier. Errors returned from redis can be explicitly checked for using the the resp2.Error type. Note that the errors.As function, introduced in go 1.13, should be used. Use the golang.org/x/xerrors package if you're using an older version of go. Implicit pipelining is an optimization implemented and enabled in the default Pool implementation (and therefore also used by Cluster and Sentinel) which involves delaying concurrent Cmds and FlatCmds a small amount of time and sending them to redis in a single batch, similar to manually using a Pipeline. By doing this radix significantly reduces the I/O and CPU overhead for concurrent requests. Note that only commands which do not block are eligible for implicit pipelining. See the documentation on Pool for more information about the current implementation of implicit pipelining and for how to configure or disable the feature. For a performance comparisons between Clients with and without implicit pipelining see the benchmark results in the README.md.
Readme
Radix is a full-featured Redis client for Go. See the reference links below for documentation and general usage examples.
Please open an issue, or start a discussion in the chat, before opening a pull request!
Standard print-like API which supports all current and future redis commands.
Connection pool which uses connection sharing to minimize system calls.
Helpers for EVAL, SCAN, Streams, and Pipelining.
Support for pubsub, as well as persistent pubsub wherein if a connection is lost a new one transparently replaces it.
API design allows for custom implementations of nearly anything.
There are two major versions of radix being supported:
v3 is the more mature version, but lacks the polished API of v4. v3 is only accepting bug fixes at this point.
v4 has feature parity with v3 and more! The biggest selling points are:
View the CHANGELOG for more details.
Radix always aims to support the most recent two versions of go, and is likely to support others prior to those two.
Module-aware mode:
go get github.com/mediocregopher/radix/v3
// import github.com/mediocregopher/radix/v3
go get github.com/mediocregopher/radix/v4
// import github.com/mediocregopher/radix/v4
# requires a redis server running on 127.0.0.1:6379
go test github.com/mediocregopher/radix/v3
go test github.com/mediocregopher/radix/v4
Benchmarks were run in as close to a "real" environment as possible. Two GCE
instances were booted up, one hosting the redis server with 2vCPUs, the other
running the benchmarks (found in the bench directory) with 16vCPUs.
The benchmarks test a variety of situations against many different redis drivers, and the results are very large. You can view them here. Below are some highlights (I've tried to be fair here):
For a typical workload, which is lots of concurrent commands with relatively small amounts of data, radix outperforms all tested drivers except redispipe:
BenchmarkDrivers/parallel/no_pipeline/small_kv/radixv4-64 17815254 2917 ns/op 199 B/op 6 allocs/op
BenchmarkDrivers/parallel/no_pipeline/small_kv/radixv3-64 16688293 3120 ns/op 109 B/op 4 allocs/op
BenchmarkDrivers/parallel/no_pipeline/small_kv/redigo-64 3504063 15092 ns/op 168 B/op 9 allocs/op
BenchmarkDrivers/parallel/no_pipeline/small_kv/redispipe_pause150us-64 31668576 1680 ns/op 217 B/op 11 allocs/op
BenchmarkDrivers/parallel/no_pipeline/small_kv/redispipe_pause0-64 31149280 1685 ns/op 218 B/op 11 allocs/op
BenchmarkDrivers/parallel/no_pipeline/small_kv/go-redis-64 3768988 14409 ns/op 411 B/op 13 allocs/op
The story is similar for pipelining commands concurrently (radixv3 doesn't do as well here, because it doesn't support connection sharing for pipeline commands):
BenchmarkDrivers/parallel/pipeline/small_kv/radixv4-64 24720337 2245 ns/op 508 B/op 13 allocs/op
BenchmarkDrivers/parallel/pipeline/small_kv/radixv3-64 6921868 7757 ns/op 165 B/op 7 allocs/op
BenchmarkDrivers/parallel/pipeline/small_kv/redigo-64 6738849 8080 ns/op 170 B/op 9 allocs/op
BenchmarkDrivers/parallel/pipeline/small_kv/redispipe_pause150us-64 44479539 1148 ns/op 316 B/op 12 allocs/op
BenchmarkDrivers/parallel/pipeline/small_kv/redispipe_pause0-64 45290868 1126 ns/op 315 B/op 12 allocs/op
BenchmarkDrivers/parallel/pipeline/small_kv/go-redis-64 6740984 7903 ns/op 475 B/op 15 allocs/op
For larger amounts of data being transferred the differences become less noticeable, but both radix versions come out on top:
BenchmarkDrivers/parallel/no_pipeline/large_kv/radixv4-64 2395707 22766 ns/op 12553 B/op 4 allocs/op
BenchmarkDrivers/parallel/no_pipeline/large_kv/radixv3-64 3150398 17087 ns/op 12745 B/op 4 allocs/op
BenchmarkDrivers/parallel/no_pipeline/large_kv/redigo-64 1593054 34038 ns/op 24742 B/op 9 allocs/op
BenchmarkDrivers/parallel/no_pipeline/large_kv/redispipe_pause150us-64 2105118 25085 ns/op 16962 B/op 11 allocs/op
BenchmarkDrivers/parallel/no_pipeline/large_kv/redispipe_pause0-64 2354427 24280 ns/op 17295 B/op 11 allocs/op
BenchmarkDrivers/parallel/no_pipeline/large_kv/go-redis-64 1519354 35745 ns/op 14033 B/op 14 allocs/op
All results above show the high-concurrency results (-cpu 64). Concurrencies
of 16 and 32 are also included in the results, but didn't show anything
different.
For serial workloads, which involve a single connection performing commands one after the other, radix is either as fast or within a couple % of the other drivers tested. This use-case is much less common, and so when tradeoffs have been made between parallel and serial performance radix has general leaned towards parallel.
Serial non-pipelined:
BenchmarkDrivers/serial/no_pipeline/small_kv/radixv4-16 346915 161493 ns/op 67 B/op 4 allocs/op
BenchmarkDrivers/serial/no_pipeline/small_kv/radixv3-16 428313 138011 ns/op 67 B/op 4 allocs/op
BenchmarkDrivers/serial/no_pipeline/small_kv/redigo-16 416103 134438 ns/op 134 B/op 8 allocs/op
BenchmarkDrivers/serial/no_pipeline/small_kv/redispipe_pause150us-16 86734 635637 ns/op 217 B/op 11 allocs/op
BenchmarkDrivers/serial/no_pipeline/small_kv/redispipe_pause0-16 340320 158732 ns/op 216 B/op 11 allocs/op
BenchmarkDrivers/serial/no_pipeline/small_kv/go-redis-16 429703 138854 ns/op 408 B/op 13 allocs/op
Serial pipelined:
BenchmarkDrivers/serial/pipeline/small_kv/radixv4-16 624417 82336 ns/op 83 B/op 5 allocs/op
BenchmarkDrivers/serial/pipeline/small_kv/radixv3-16 784947 68540 ns/op 163 B/op 7 allocs/op
BenchmarkDrivers/serial/pipeline/small_kv/redigo-16 770983 69976 ns/op 134 B/op 8 allocs/op
BenchmarkDrivers/serial/pipeline/small_kv/redispipe_pause150us-16 175623 320512 ns/op 312 B/op 12 allocs/op
BenchmarkDrivers/serial/pipeline/small_kv/redispipe_pause0-16 642673 82225 ns/op 312 B/op 12 allocs/op
BenchmarkDrivers/serial/pipeline/small_kv/go-redis-16 787364 72240 ns/op 472 B/op 15 allocs/op
Serial large values:
BenchmarkDrivers/serial/no_pipeline/large_kv/radixv4-16 253586 217600 ns/op 12521 B/op 4 allocs/op
BenchmarkDrivers/serial/no_pipeline/large_kv/radixv3-16 317356 179608 ns/op 12717 B/op 4 allocs/op
BenchmarkDrivers/serial/no_pipeline/large_kv/redigo-16 244226 231179 ns/op 24704 B/op 8 allocs/op
BenchmarkDrivers/serial/no_pipeline/large_kv/redispipe_pause150us-16 80174 674066 ns/op 13780 B/op 11 allocs/op
BenchmarkDrivers/serial/no_pipeline/large_kv/redispipe_pause0-16 251810 209890 ns/op 13778 B/op 11 allocs/op
BenchmarkDrivers/serial/no_pipeline/large_kv/go-redis-16 236379 225677 ns/op 13976 B/op 14 allocs/op
Unless otherwise noted, the source files are distributed under the MIT License found in the LICENSE.txt file.
FAQs
Package radix implements all functionality needed to work with redis and all things related to it, including redis cluster, pubsub, sentinel, scanning, lua scripting, and more. For a single node redis instance use NewPool to create a connection pool. The connection pool is thread-safe and will automatically create, reuse, and recreate connections as needed: If you're using sentinel or cluster you should use NewSentinel or NewCluster (respectively) to create your client instead. Any redis command can be performed by passing a Cmd into a Client's Do method. Each Cmd should only be used once. The return from the Cmd can be captured into any appopriate go primitive type, or a slice, map, or struct, if the command returns an array. FlatCmd can also be used if you wish to use non-string arguments like integers, slices, maps, or structs, and have them automatically be flattened into a single string slice. Cmd and FlatCmd can unmarshal results into a struct. The results must be a key/value array, such as that returned by HGETALL. Exported field names will be used as keys, unless the fields have the "redis" tag: Embedded structs will inline that struct's fields into the parent's: The same rules for field naming apply when a struct is passed into FlatCmd as an argument. Cmd and FlatCmd both implement the Action interface. Other Actions include Pipeline, WithConn, and EvalScript.Cmd. Any of these may be passed into any Client's Do method. There are two ways to perform transactions in redis. The first is with the MULTI/EXEC commands, which can be done using the WithConn Action (see its example). The second is using EVAL with lua scripting, which can be done using the EvalScript Action (again, see its example). EVAL with lua scripting is recommended in almost all cases. It only requires a single round-trip, it's infinitely more flexible than MULTI/EXEC, it's simpler to code, and for complex transactions, which would otherwise need a WATCH statement with MULTI/EXEC, it's significantly faster. All the client creation functions (e.g. NewPool) take in either a ConnFunc or a ClientFunc via their options. These can be used in order to set up timeouts on connections, perform authentication commands, or even implement custom pools. All interfaces in this package were designed such that they could have custom implementations. There is no dependency within radix that demands any interface be implemented by a particular underlying type, so feel free to create your own Pools or Conns or Actions or whatever makes your life easier. Errors returned from redis can be explicitly checked for using the the resp2.Error type. Note that the errors.As function, introduced in go 1.13, should be used. Use the golang.org/x/xerrors package if you're using an older version of go. Implicit pipelining is an optimization implemented and enabled in the default Pool implementation (and therefore also used by Cluster and Sentinel) which involves delaying concurrent Cmds and FlatCmds a small amount of time and sending them to redis in a single batch, similar to manually using a Pipeline. By doing this radix significantly reduces the I/O and CPU overhead for concurrent requests. Note that only commands which do not block are eligible for implicit pipelining. See the documentation on Pool for more information about the current implementation of implicit pipelining and for how to configure or disable the feature. For a performance comparisons between Clients with and without implicit pipelining see the benchmark results in the README.md.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A hospital in Mobile, Alabama, agreed to a settlement in a landmark ransomware death lawsuit, but is now reportedly reconsidering the agreement and refusing to pay.
Security News
A new report explores how advancements in LLMs are enhancing cyber threats, including polymorphic malware, personalized spearphishing, and the risk of hijacking customer service bots.
Security News
ESLint has approved an RFC that adds support for TypeScript configuration files, which is aimed at improving the developer experience and recognizing changes in the evolving JavaScript ecosystem.