redis

package module
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 17, 2020 License: Apache-2.0 Imports: 14 Imported by: 0

README

redis-go-cluster

redis-go-cluster is a golang implementation of redis client based on Gary Burd's Redigo. It caches slot info at local and updates it automatically when cluster change. The client manages a connection pool for each node, uses goroutine to execute as concurrently as possible, which leads to its high efficiency and low lantency.

Supported:

  • Most commands of keys, strings, lists, sets, sorted sets, hashes.
  • MGET/MSET
  • Pipelining

NOT supported:

  • Cluster commands
  • Pub/Sub
  • Transaction
  • Lua script

Documentation

API Reference

Installation

Install redis-go-cluster with go tool:

    go get github.com/chasex/redis-go-cluster

Usage

To use redis cluster, you need import the package and create a new cluster client with an options:

import "github.com/chasex/redis-go-cluster"

cluster, err := redis.NewCluster(
    &redis.Options{
	StartNodes: []string{"127.0.0.1:7000", "127.0.0.1:7001", "127.0.0.1:7002"},
	ConnTimeout: 50 * time.Millisecond,
	ReadTimeout: 50 * time.Millisecond,
	WriteTimeout: 50 * time.Millisecond,
	KeepAlive: 16,
	AliveTime: 60 * time.Second,
    })
Basic

redis-go-cluster has compatible interface to Redigo, which uses a print-like API for all redis commands. When executing a command, it need a key to hash to a slot, then find the corresponding redis node. Do method will choose first argument in args as the key, so commands which are independent from keys are not supported, such as SYNC, BGSAVE, RANDOMKEY, etc.

RESTRICTION: Please be sure the first argument in args is key.

See full redis commands: http://www.redis.io/commands

cluster.Do("SET", "foo", "bar")
cluster.Do("INCR", "mycount", 1)
cluster.Do("LPUSH", "mylist", "foo", "bar")
cluster.Do("HMSET", "myhash", "f1", "foo", "f2", "bar")

You can use help functions to convert reply to int, float, string, etc.

reply, err := Int(cluster.Do("INCR", "mycount", 1))
reply, err := String(cluster.Do("GET", "foo"))
reply, err := Strings(cluster.Do("LRANGE", "mylist", 0, -1))
reply, err := StringMap(cluster.Do("HGETALL", "myhash"))

Also, you can use Values and Scan to convert replies to multiple values with different types.

_, err := cluster.Do("MSET", "key1", "foo", "key2", 1024, "key3", 3.14, "key4", "false")
reply, err := Values(cluster.Do("MGET", "key1", "key2", "key3", "key4"))
var val1 string
var val2 int
reply, err = Scan(reply, &val1, &val2)
var val3 float64
reply, err = Scan(reply, &val3)
var val4 bool
reply, err = Scan(reply, &val4)
Multi-keys

Mutiple keys command - MGET/MSET are supported using result aggregation. Processing steps are as follows:

  • First, split the keys into multiple nodes according to their hash slot.
  • Then, start a goroutine for each node to excute MGET/MSET commands and wait them finish.
  • Last, collect and rerange all replies, return back to caller.

NOTE: Since the keys may spread across mutiple node, there's no atomicity gurantee that all keys will be set at once. It's possible that some keys are set while others are not.

Pipelining

Pipelining is supported through the Batch interface. You can put multiple commands into a batch as long as it is supported by Do method. RunBatch will split these command to distinct nodes and start a goroutine for each node. Commands hash to same nodes will be merged and sent using pipelining. After all commands done, it rearrange results as MGET/MSET do. Result is a slice of each command's reply, you can use Scan to convert them to other types.

batch := cluster.NewBatch()
err = batch.Put("LPUSH", "country_list", "France")
err = batch.Put("LPUSH", "country_list", "Italy")
err = batch.Put("LPUSH", "country_list", "Germany")
err = batch.Put("INCRBY", "countries", 3)
err = batch.Put("LRANGE", "country_list", 0, -1)
reply, err = cluster.RunBatch(batch)

var resp int
for i := 0; i < 4; i++ {
    reply, err = redis.Scan(reply, &resp)    
}

countries, err := Strings(reply[0], nil)

Contact

Bug reports and feature requests are welcome. If you have any question, please email me wuxibin2012@gmail.com.

License

redis-go-cluster is available under the Apache License, Version 2.0.

Documentation

Overview

Package redis implement a pure redis cluster client, meaning it doesn't support any cluster commands.

Create a new cluster client with specified options: 

cluster, err := redis.NewCluster(
    &redis.Options{
	StartNodes: []string{"127.0.0.1:7000", "127.0.0.1:7001", "127.0.0.1:7002"},
	ConnTimeout: 50 * time.Millisecond,
	ReadTimeout: 50 * time.Millisecond,
	WriteTimeout: 50 * time.Millisecond,
	KeepAlive: 16,
	AliveTime: 60 * time.Second,
})

For basic usage: 

cluster.Do("SET", "foo", "bar")
cluster.Do("INCR", "mycount", 1)
cluster.Do("LPUSH", "mylist", "foo", "bar")
cluster.Do("HMSET", "myhash", "f1", "foo", "f2", "bar")

Use convert help functions to convert replies to int, float, string, etc: 

reply, err := Int(cluster.Do("INCR", "mycount", 1))
reply, err := String(cluster.Do("GET", "foo"))
reply, err := Strings(cluster.Do("LRANGE", "mylist", 0, -1))
reply, err := StringMap(cluster.Do("HGETALL", "myhash"))

Use batch interface to pack multiple commands for pipelining: 

batch := cluster.NewBatch()
batch.Put("LPUSH", "country_list", "France")
batch.Put("LPUSH", "country_list", "Italy")
batch.Put("LPUSH", "country_list", "Germany")
batch.Put("INCRBY", "countries", 3)
batch.Put("LRANGE", "country_list", 0, -1)

Index

Constants

This section is empty.

Variables

View Source 
var ErrNil = errors.New("nil reply")

ErrNil indicates that a reply value is nil.

Functions

func Bool 

func Bool(reply interface{}, err error) (bool, error)

Bool is a helper that converts a command reply to a boolean. If err is not equal to nil, then Bool returns false, err. Otherwise Bool converts the reply to boolean as follows: 

Reply type      Result
integer         value != 0, nil
bulk string     strconv.ParseBool(reply)
nil             false, ErrNil
other           false, error

func Bytes 

func Bytes(reply interface{}, err error) ([]byte, error)

Bytes is a helper that converts a command reply to a slice of bytes. If err is not equal to nil, then Bytes returns nil, err. Otherwise Bytes converts the reply to a slice of bytes as follows: 

Reply type      Result
bulk string     reply, nil
simple string   []byte(reply), nil
nil             nil, ErrNil
other           nil, error

func Float64 

func Float64(reply interface{}, err error) (float64, error)

Float64 is a helper that converts a command reply to 64 bit float. If err is not equal to nil, then Float64 returns 0, err. Otherwise, Float64 converts the reply to an int as follows: 

Reply type    Result
bulk string   parsed reply, nil
nil           0, ErrNil
other         0, error

func GetSlot added in v1.0.1 

func GetSlot(arg interface{}) (uint16, error)

func Int 

func Int(reply interface{}, err error) (int, error)

Int is a helper that converts a command reply to an integer. If err is not equal to nil, then Int returns 0, err. Otherwise, Int converts the reply to an int as follows: 

Reply type    Result
integer       int(reply), nil
bulk string   parsed reply, nil
nil           0, ErrNil
other         0, error

func Int64 

func Int64(reply interface{}, err error) (int64, error)

Int64 is a helper that converts a command reply to 64 bit integer. If err is not equal to nil, then Int returns 0, err. Otherwise, Int64 converts the reply to an int64 as follows: 

Reply type    Result
integer       reply, nil
bulk string   parsed reply, nil
nil           0, ErrNil
other         0, error

func Ints 

func Ints(reply interface{}, err error) ([]int, error)

Ints is a helper that converts an array command reply to a []int. If err is not equal to nil, then Ints returns nil, err.

func Scan 

func Scan(src []interface{}, dst ...interface{}) ([]interface{}, error)

Scan copies from src to the values pointed at by dest.

The values pointed at by dest must be an integer, float, boolean, string, []byte, interface{} or slices of these types. Scan uses the standard strconv package to convert bulk strings to numeric and boolean types.

If a dest value is nil, then the corresponding src value is skipped.

If a src element is nil, then the corresponding dest value is not modified.

To enable easy use of Scan in a loop, Scan returns the slice of src following the copied values.

func String 

func String(reply interface{}, err error) (string, error)

String is a helper that converts a command reply to a string. If err is not equal to nil, then String returns "", err. Otherwise String converts the reply to a string as follows: 

Reply type      Result
bulk string     string(reply), nil
simple string   reply, nil
nil             "",  ErrNil
other           "",  error

func StringMap 

func StringMap(result interface{}, err error) (map[string]string, error)

StringMap is a helper that converts an array of strings (alternating key, value) into a map[string]string. The HGETALL and CONFIG GET commands return replies in this format. Requires an even number of values in result.

func Strings 

func Strings(reply interface{}, err error) ([]string, error)

Strings is a helper that converts an array command reply to a []string. If err is not equal to nil, then Strings returns nil, err. Nil array items are converted to "" in the output slice. Strings returns an error if an array item is not a bulk string or nil.

func Values 

func Values(reply interface{}, err error) ([]interface{}, error)

Values is a helper that converts an array command reply to a []interface{}. If err is not equal to nil, then Values returns nil, err. Otherwise, Values converts the reply as follows: 

Reply type      Result
array           reply, nil
nil             nil, ErrNil
other           nil, error

Types

type Batch 

type Batch struct {
	// contains filtered or unexported fields
}

Batch pack multiple commands, which should be supported by Do method.

func (*Batch) GetBatchSize added in v1.0.1 

func (batch *Batch) GetBatchSize() int

func (*Batch) Put 

func (batch *Batch) Put(cmd string, args ...interface{}) error

Put add a redis command to batch, DO NOT put MGET/MSET/MSETNX.

type Cluster 

type Cluster struct {
	// contains filtered or unexported fields
}

Cluster is a redis client that manage connections to redis nodes, cache and update cluster info, and execute all kinds of commands. Multiple goroutines may invoke methods on a cluster simutaneously.

func NewCluster 

func NewCluster(options *Options) (*Cluster, error)

NewCluster create a new redis cluster client with specified options.

func (*Cluster) ChooseNodeWithCmd added in v1.0.1 

func (cluster *Cluster) ChooseNodeWithCmd(cmd string, args ...interface{}) (*redisNode, error)

func (*Cluster) Close added in v1.0.1 

func (cluster *Cluster) Close()

Close cluster connection, any subsequent method call will fail.

func (*Cluster) Do 

func (cluster *Cluster) Do(cmd string, args ...interface{}) (interface{}, error)

Do excute a redis command with random number arguments. First argument will be used as key to hash to a slot, so it only supports a subset of redis commands. / SUPPORTED: most commands of keys, strings, lists, sets, sorted sets, hashes. NOT SUPPORTED: scripts, transactions, clusters.

Particularly, MSET/MSETNX/MGET are supported using result aggregation. To MSET/MSETNX, there's no atomicity gurantee that given keys are set at once. It's possible that some keys are set, while others not.

See README.md for more details. See full redis command list: http://www.redis.io/commands

func (*Cluster) NewBatch 

func (cluster *Cluster) NewBatch() *Batch

NewBatch create a new batch to pack mutiple commands.

func (*Cluster) RunBatch 

func (cluster *Cluster) RunBatch(bat *Batch) ([]interface{}, error)

RunBatch execute commands in batch simutaneously. If multiple commands are directed to the same node, they will be merged and sent at once using pipeling.

type Options 

type Options struct {
	StartNodes []string // Startup nodes

	ConnTimeout  time.Duration // Connection timeout
	ReadTimeout  time.Duration // Read timeout
	WriteTimeout time.Duration // Write timeout

	KeepAlive int           // Maximum keep alive connecion in each node
	AliveTime time.Duration // Keep alive timeout

	Password string
}

Options is used to initialize a new redis cluster.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.