Documentation ¶
Overview ¶
Package redis provides access to Redis nodes. See <https://redis.io/topics/introduction> for the concept.
Index ¶
- Constants
- Variables
- func ParseInt(bytes []byte) int64
- type Client
- func (c *Client) APPEND(key string, value []byte) (newLen int64, err error)
- func (c *Client) APPENDString(key, value string) (newLen int64, err error)
- func (c *Client) BytesAPPEND(key, value []byte) (newLen int64, err error)
- func (c *Client) BytesDEL(key []byte) (bool, error)
- func (c *Client) BytesDELArgs(keys ...[]byte) (int64, error)
- func (c *Client) BytesGET(key []byte) (value []byte, err error)
- func (c *Client) BytesGETRANGE(key []byte, start, end int64) ([]byte, error)
- func (c *Client) BytesHDEL(key, field []byte) (bool, error)
- func (c *Client) BytesHDELArgs(key []byte, fields ...[]byte) (int64, error)
- func (c *Client) BytesHGET(key, field []byte) (value []byte, err error)
- func (c *Client) BytesHMGET(key []byte, fields ...[]byte) (values [][]byte, err error)
- func (c *Client) BytesHMSET(key []byte, fields, values [][]byte) error
- func (c *Client) BytesHSET(key, field, value []byte) (newField bool, err error)
- func (c *Client) BytesINCR(key []byte) (newValue int64, err error)
- func (c *Client) BytesINCRBY(key []byte, increment int64) (newValue int64, err error)
- func (c *Client) BytesLINDEX(key []byte, index int64) (value []byte, err error)
- func (c *Client) BytesLLEN(key []byte) (int64, error)
- func (c *Client) BytesLPOP(key []byte) (value []byte, err error)
- func (c *Client) BytesLPUSH(key, value []byte) (newLen int64, err error)
- func (c *Client) BytesLRANGE(key []byte, start, stop int64) (values [][]byte, err error)
- func (c *Client) BytesLSET(key []byte, index int64, value []byte) error
- func (c *Client) BytesLTRIM(key []byte, start, stop int64) error
- func (c *Client) BytesMGET(keys ...[]byte) (values [][]byte, err error)
- func (c *Client) BytesMOVE(key []byte, db int64) (bool, error)
- func (c *Client) BytesMSET(keys, values [][]byte) error
- func (c *Client) BytesRPOP(key []byte) (value []byte, err error)
- func (c *Client) BytesRPUSH(key, value []byte) (newLen int64, err error)
- func (c *Client) BytesSET(key, value []byte) error
- func (c *Client) BytesSETWithOptions(key, value []byte, o SETOptions) (bool, error)
- func (c *Client) BytesSTRLEN(key []byte) (int64, error)
- func (c *Client) Close() error
- func (c *Client) DEL(key string) (bool, error)
- func (c *Client) DELArgs(keys ...string) (int64, error)
- func (c *Client) FLUSHALL(async bool) error
- func (c *Client) FLUSHDB(async bool) error
- func (c *Client) GET(key string) (value []byte, err error)
- func (c *Client) GETRANGE(key string, start, end int64) ([]byte, error)
- func (c *Client) GETRANGEString(key string, start, end int64) (string, error)
- func (c *Client) GETString(key string) (value string, ok bool, err error)
- func (c *Client) HDEL(key, field string) (bool, error)
- func (c *Client) HDELArgs(key string, fields ...string) (int64, error)
- func (c *Client) HGET(key, field string) (value []byte, err error)
- func (c *Client) HGETString(key, field string) (value string, ok bool, err error)
- func (c *Client) HMGET(key string, fields ...string) (values [][]byte, err error)
- func (c *Client) HMGETString(key string, fields ...string) (values []string, err error)
- func (c *Client) HMSET(key string, fields []string, values [][]byte) error
- func (c *Client) HMSETString(key string, fields, values []string) error
- func (c *Client) HSET(key, field string, value []byte) (newField bool, err error)
- func (c *Client) HSETString(key, field, value string) (updated bool, err error)
- func (c *Client) INCR(key string) (newValue int64, err error)
- func (c *Client) INCRBY(key string, increment int64) (newValue int64, err error)
- func (c *Client) LINDEX(key string, index int64) (value []byte, err error)
- func (c *Client) LINDEXString(key string, index int64) (value string, ok bool, err error)
- func (c *Client) LLEN(key string) (int64, error)
- func (c *Client) LPOP(key string) (value []byte, err error)
- func (c *Client) LPOPString(key string) (value string, ok bool, err error)
- func (c *Client) LPUSH(key string, value []byte) (newLen int64, err error)
- func (c *Client) LPUSHString(key, value string) (newLen int64, err error)
- func (c *Client) LRANGE(key string, start, stop int64) (values [][]byte, err error)
- func (c *Client) LRANGEString(key string, start, stop int64) (values []string, err error)
- func (c *Client) LSET(key string, index int64, value []byte) error
- func (c *Client) LSETString(key string, index int64, value string) error
- func (c *Client) LTRIM(key string, start, stop int64) error
- func (c *Client) MGET(keys ...string) (values [][]byte, err error)
- func (c *Client) MGETString(keys ...string) (values []string, err error)
- func (c *Client) MOVE(key string, db int64) (bool, error)
- func (c *Client) MSET(keys []string, values [][]byte) error
- func (c *Client) MSETString(keys, values []string) error
- func (c *Client) PUBLISH(channel string, message []byte) (clientCount int64, err error)
- func (c *Client) PUBLISHString(channel, message string) (clientCount int64, err error)
- func (c *Client) RPOP(key string) (value []byte, err error)
- func (c *Client) RPOPString(key string) (value string, ok bool, err error)
- func (c *Client) RPUSH(key string, value []byte) (newLen int64, err error)
- func (c *Client) RPUSHString(key, value string) (newLen int64, err error)
- func (c *Client) SELECT(db int64) errordeprecated
- func (c *Client) SET(key string, value []byte) error
- func (c *Client) SETString(key, value string) error
- func (c *Client) SETStringWithOptions(key, value string, o SETOptions) (bool, error)
- func (c *Client) SETWithOptions(key string, value []byte, o SETOptions) (bool, error)
- func (c *Client) STRLEN(key string) (int64, error)
- type ClientConfig
- type Listener
- type ListenerConfig
- type SETOptions
- type ServerError
Examples ¶
Constants ¶
const ( // NX only sets the key if it does not already exist. NX = 1 << iota // XX only sets the key if it does already exist. XX // EX sets an expire time, in seconds. EX // PX sets an expire time, in milliseconds. PX )
Flags For SETOptions
const ( // SizeMax is the upper boundary for byte sizes. // A string value can be at most 512 MiB in length. SizeMax = 512 << 20 // KeyMax is the upper boundary for key counts. // Redis can handle up to 2³² keys. KeyMax = 1 << 32 // ElementMax is the upper boundary for element counts. // Every hash, list, set, and sorted set, can hold 2³² − 1 elements. ElementMax = 1<<32 - 1 )
Server Limits
const DialDelayMax = time.Second / 2
DialDelayMax is the idle limit for automated reconnect attempts. Sequential failure with connection establisment increases the retry delay in steps from 0 to 500 ms.
Variables ¶
var ErrClosed = errors.New("redis: connection establishment closed")
ErrClosed signals end-of-life due a call to Close.
Functions ¶
Types ¶
type Client ¶
type Client struct { // Normalized node address in use. This field is read-only. Addr string // contains filtered or unexported fields }
Client manages a connection to a Redis node until Close. Broken connection states cause automated reconnects.
Multiple goroutines may invoke methods on a Client simultaneously. Command invocation applies <https://redis.io/topics/pipelining> on concurrency.
func NewClient ¶
NewClient launches a managed connection to a node (address). The host defaults to localhost, and the port defaults to 6379. Thus, the empty string defaults to "localhost:6379". Use an absolute file path (e.g. "/var/run/redis.sock") for Unix domain sockets.
A command time-out limits execution duration when nonzero. Expiry causes a reconnect (to prevent stale connections) and a net.Error with Timeout() true.
The dial time-out limits the duration for network connection establishment. Expiry causes an abort + retry. Zero defaults to one second. Any command submission blocks on the first attempt. When connection establishment fails, then command submission receives the error of the last attempt, until the connection restores.
func (*Client) APPEND ¶
APPEND executes <https://redis.io/commands/append>.
func (*Client) APPENDString ¶
APPENDString executes <https://redis.io/commands/append>.
func (*Client) BytesAPPEND ¶
BytesAPPEND executes <https://redis.io/commands/append>.
func (*Client) BytesDEL ¶
BytesDEL executes <https://redis.io/commands/del>.
func (*Client) BytesDELArgs ¶ added in v1.2.0
BytesDELArgs executes <https://redis.io/commands/del>.
func (*Client) BytesGET ¶
BytesGET executes <https://redis.io/commands/get>. The return is nil if key does not exist.
func (*Client) BytesGETRANGE ¶ added in v1.4.0
BytesGETRANGE executes <https://redis.io/commands/getrange>.
func (*Client) BytesHDEL ¶
BytesHDEL executes <https://redis.io/commands/hdel>.
func (*Client) BytesHDELArgs ¶ added in v1.2.0
BytesHDELArgs executes <https://redis.io/commands/hdel>.
func (*Client) BytesHGET ¶
BytesHGET executes <https://redis.io/commands/hget>. The return is nil if key does not exist.
func (*Client) BytesHMGET ¶ added in v1.2.0
BytesHMGET executes <https://redis.io/commands/hmget>. For every field that does not exist, a nil value is returned.
func (*Client) BytesHMSET ¶ added in v1.2.0
BytesHMSET executes <https://redis.io/commands/hmset>.
func (*Client) BytesHSET ¶
BytesHSET executes <https://redis.io/commands/hset>.
func (*Client) BytesINCR ¶
BytesINCR executes <https://redis.io/commands/incr>.
func (*Client) BytesINCRBY ¶
BytesINCRBY executes <https://redis.io/commands/incrby>.
func (*Client) BytesLINDEX ¶
BytesLINDEX executes <https://redis.io/commands/lindex>. The return is nil if key does not exist. The return is nil if index is out of range.
func (*Client) BytesLLEN ¶
BytesLLEN executes <https://redis.io/commands/llen>. The return is 0 if key does not exist.
func (*Client) BytesLPOP ¶
BytesLPOP executes <https://redis.io/commands/lpop>. The return is nil if key does not exist.
func (*Client) BytesLPUSH ¶
BytesLPUSH executes <https://redis.io/commands/lpush>.
func (*Client) BytesLRANGE ¶
BytesLRANGE executes <https://redis.io/commands/lrange>. The return is empty if key does not exist.
func (*Client) BytesLSET ¶
BytesLSET executes <https://redis.io/commands/lset>.
func (*Client) BytesLTRIM ¶
BytesLTRIM executes <https://redis.io/commands/ltrim>.
func (*Client) BytesMGET ¶ added in v1.2.0
BytesMGET executes <https://redis.io/commands/mget>. For every key that does not exist, a nil value is returned.
func (*Client) BytesMOVE ¶ added in v1.1.0
BytesMOVE executes <https://redis.io/commands/move>.
func (*Client) BytesMSET ¶ added in v1.2.0
BytesMSET executes <https://redis.io/commands/mset>.
func (*Client) BytesRPOP ¶
BytesRPOP executes <https://redis.io/commands/rpop>. The return is nil if key does not exist.
func (*Client) BytesRPUSH ¶
BytesRPUSH executes <https://redis.io/commands/rpush>.
func (*Client) BytesSET ¶
BytesSET executes <https://redis.io/commands/set>.
func (*Client) BytesSETWithOptions ¶ added in v1.4.0
func (c *Client) BytesSETWithOptions(key, value []byte, o SETOptions) (bool, error)
BytesSETWithOptions executes <https://redis.io/commands/set> with options. The return is false if the SET operation was not performed due to an NX or XX condition.
func (*Client) BytesSTRLEN ¶ added in v1.4.0
BytesSTRLEN executes <https://redis.io/commands/strlen>.
func (*Client) Close ¶ added in v1.2.0
Close terminates the connection establishment. Command submission is stopped with ErrClosed. All pending commands are dealt with on return. Calling Close more than once has no effect.
func (*Client) DEL ¶
DEL executes <https://redis.io/commands/del>.
func (*Client) DELArgs ¶ added in v1.2.0
DELArgs executes <https://redis.io/commands/del>.
func (*Client) FLUSHALL ¶ added in v1.1.0
FLUSHALL executes <https://redis.io/commands/flushall>.
func (*Client) FLUSHDB ¶ added in v1.1.0
FLUSHDB executes <https://redis.io/commands/flushdb>.
func (*Client) GET ¶
GET executes <https://redis.io/commands/get>. The return is nil if key does not exist.
func (*Client) GETRANGE ¶ added in v1.4.0
GETRANGE executes <https://redis.io/commands/getrange>.
func (*Client) GETRANGEString ¶ added in v1.4.0
GETRANGEString executes <https://redis.io/commands/getrange>.
func (*Client) GETString ¶ added in v1.4.0
GETString executes <https://redis.io/commands/get>. Boolean ok is false if key does not exist.
func (*Client) HDEL ¶
HDEL executes <https://redis.io/commands/hdel>.
func (*Client) HDELArgs ¶ added in v1.2.0
HDELArgs executes <https://redis.io/commands/hdel>.
func (*Client) HGET ¶
HGET executes <https://redis.io/commands/hget>. The return is nil if key does not exist.
func (*Client) HGETString ¶ added in v1.4.0
HGETString executes <https://redis.io/commands/hget>. Boolean ok is false if key does not exist.
func (*Client) HMGET ¶ added in v1.2.0
HMGET executes <https://redis.io/commands/hmget>. For every field that does not exist, a nil value is returned.
func (*Client) HMGETString ¶ added in v1.4.0
HMGETString executes <https://redis.io/commands/hmget>. For every field that does not exist, an empty string is returned.
func (*Client) HMSET ¶ added in v1.2.0
HMSET executes <https://redis.io/commands/hmset>.
func (*Client) HMSETString ¶ added in v1.2.0
HMSETString executes <https://redis.io/commands/hmset>.
func (*Client) HSET ¶
HSET executes <https://redis.io/commands/hset>.
func (*Client) HSETString ¶
HSETString executes <https://redis.io/commands/hset>.
func (*Client) INCR ¶
INCR executes <https://redis.io/commands/incr>.
func (*Client) INCRBY ¶
INCRBY executes <https://redis.io/commands/incrby>.
func (*Client) LINDEX ¶
LINDEX executes <https://redis.io/commands/lindex>. The return is nil if key does not exist. The return is nil if index is out of range.
func (*Client) LINDEXString ¶ added in v1.4.0
LINDEXString executes <https://redis.io/commands/lindex>. Boolean ok is false if key does not exist. Boolean ok is false if index is out of range.
func (*Client) LLEN ¶
LLEN executes <https://redis.io/commands/llen>. The return is 0 if key does not exist.
func (*Client) LPOP ¶
LPOP executes <https://redis.io/commands/lpop>. The return is nil if key does not exist.
func (*Client) LPOPString ¶ added in v1.4.0
LPOPString executes <https://redis.io/commands/lpop>. Boolean ok is false if key does not exist.
func (*Client) LPUSH ¶
LPUSH executes <https://redis.io/commands/lpush>.
func (*Client) LPUSHString ¶
LPUSHString executes <https://redis.io/commands/lpush>.
func (*Client) LRANGE ¶
LRANGE executes <https://redis.io/commands/lrange>. The return is empty if key does not exist.
func (*Client) LRANGEString ¶ added in v1.4.0
LRANGEString executes <https://redis.io/commands/lrange>. The return is empty if key does not exist.
func (*Client) LSET ¶
LSET executes <https://redis.io/commands/lset>.
func (*Client) LSETString ¶
LSETString executes <https://redis.io/commands/lset>.
func (*Client) LTRIM ¶
LTRIM executes <https://redis.io/commands/ltrim>.
func (*Client) MGET ¶ added in v1.2.0
MGET executes <https://redis.io/commands/mget>. For every key that does not exist, a nil value is returned.
func (*Client) MGETString ¶ added in v1.4.0
MGETString executes <https://redis.io/commands/mget>. For every key that does not exist, an empty string is returned.
func (*Client) MOVE ¶ added in v1.1.0
MOVE executes <https://redis.io/commands/move>.
func (*Client) MSET ¶ added in v1.2.0
MSET executes <https://redis.io/commands/mset>.
func (*Client) MSETString ¶ added in v1.2.0
MSETString executes <https://redis.io/commands/mset>.
func (*Client) PUBLISH ¶ added in v1.4.0
PUBLISH executes <https://redis.io/commands/publish>.
func (*Client) PUBLISHString ¶ added in v1.4.0
PUBLISHString executes <https://redis.io/commands/publish>.
func (*Client) RPOP ¶
RPOP executes <https://redis.io/commands/rpop>. The return is nil if key does not exist.
func (*Client) RPOPString ¶ added in v1.4.0
RPOPString executes <https://redis.io/commands/rpop>. Boolean ok is false if key does not exist.
func (*Client) RPUSH ¶
RPUSH executes <https://redis.io/commands/rpush>.
func (*Client) RPUSHString ¶
RPUSHString executes <https://redis.io/commands/rpush>.
func (*Client) SELECT
deprecated
added in
v1.1.0
SELECT executes <https://redis.io/commands/select> in a persistent way, even when the return is in error. Any following command executions apply to this database selection, reconnects included.
Deprecated: Use ClientConfig.DB instead. The SELECT method has unintuitive behaviour on error scenario.
func (*Client) SET ¶
SET executes <https://redis.io/commands/set>.
func (*Client) SETString ¶
SETString executes <https://redis.io/commands/set>.
func (*Client) SETStringWithOptions ¶ added in v1.4.0
func (c *Client) SETStringWithOptions(key, value string, o SETOptions) (bool, error)
SETStringWithOptions executes <https://redis.io/commands/set> with options. The return is false if the SET operation was not performed due to an NX or XX condition.
Example ¶
package main import ( "log" "time" "github.com/pascaldekloe/redis" ) func main() { // connection setup var Redis = redis.NewClient("rds1.example.com", time.Second/2, 0) defer Redis.Close() // execute command ok, err := Redis.SETStringWithOptions("k", "v", redis.SETOptions{ Flags: redis.NX | redis.EX, Expire: time.Minute, }) if err != nil { log.Print("command error: ", err) return } // evaluate NX condition if ok { log.Print("new string expires in a minute") } else { log.Print("left existing string as is") } }
Output:
func (*Client) SETWithOptions ¶ added in v1.4.0
SETWithOptions executes <https://redis.io/commands/set> with options. The return is false if the SET operation was not performed due to an NX or XX condition.
type ClientConfig ¶ added in v1.4.0
type ClientConfig struct { // The host defaults to localhost, and the port defaults to 6379. // Thus, the empty string defaults to "localhost:6379". Use an // absolute file path (e.g. "/var/run/redis.sock") for Unix // domain sockets. Addr string // Limit execution duration when nonzero. Expiry causes a reconnect // to prevent stale connections and a net.Error with Timeout() true. CommandTimeout time.Duration // Limit the duration for network connection establishment. Expiry // causes an abort plus retry. See net.Dialer Timeout for details. // Zero defaults to one second. // // Command submission blocks during the first dial attempt. When the // connect fails, then command submission receives the error of the last // connect attempt until the connection restores. DialTimeout time.Duration // AUTH when not nil. Password []byte // SELECT when not zero. DB int64 }
ClientConfig defines a Client setup.
func (*ClientConfig) NewClient ¶ added in v1.4.0
func (c *ClientConfig) NewClient() *Client
NewClient launches a managed connection to a node (address).
type Listener ¶ added in v1.4.0
type Listener struct { ListenerConfig // read-only attributes // contains filtered or unexported fields }
Listener manages a connection to a Redis node until Close. Broken connection states cause automated reconnects, including resubscribes when applicable.
Multiple goroutines may invoke methods on a Listener simultaneously.
Example ¶
package main import ( "io" "log" "time" "github.com/pascaldekloe/redis" ) func main() { // connection setup var RedisListener = redis.NewListener(redis.ListenerConfig{ Func: func(channel string, message []byte, err error) { switch err { case nil: log.Printf("received %q on %q", message, channel) case redis.ErrClosed: log.Print("subscription establishment terminated") case io.ErrShortBuffer: // see ListenerConfig BufferSize log.Printf("message on %q skipped due size", channel) default: log.Print("subscription error: ", err) // recovery attempts follow automatically } }, Addr: "rds1.example.com:6379", }) defer RedisListener.Close() // listen quickly RedisListener.SUBSCRIBE("demo_channel") time.Sleep(time.Millisecond) }
Output:
func NewListener ¶ added in v1.4.0
func NewListener(config ListenerConfig) *Listener
NewListener launches a managed connection.
func (*Listener) Close ¶ added in v1.4.0
Close terminates the connection establishment. The Listener Func is called with ErrClosed before return, and after the network connection was closed. Calling Close more than once just blocks until the first call completed.
func (*Listener) SUBSCRIBE ¶ added in v1.4.0
SUBSCRIBE executes <https://redis.io/commands/subscribe> in a persistent manner. New connections automatically re-subscribe (until UNSUBSCRIBE).
func (*Listener) UNSUBSCRIBE ¶ added in v1.4.0
UNSUBSCRIBE executes <https://redis.io/commands/unsubscribe>, yet never with zero arguments.
type ListenerConfig ¶ added in v1.4.0
type ListenerConfig struct { // Func is the callback interface for both push messages and error // events. Implementations must not retain message—make a copy if the // bytes are used after return. Message invocation is guaranteed to // match the Redis submission order. Slow or blocking receivers should // spawn of in a separate routine. Func func(channel string, message []byte, err error) // Upper boundary for the number of bytes in a message payload. // Larger messages are skipped with an io.ErrShortBuffer to Func. // Zero defaults to 32 KiB. Values larger than SizeMax are capped // to SizeMax. BufferSize int // The host defaults to localhost, and the port defaults to 6379. // Thus, the empty string defaults to "localhost:6379". Use an // absolute file path (e.g. "/var/run/redis.sock") for Unix // domain sockets. Addr string // Limit execution duration of AUTH, QUIT, SUBSCRIBE & UNSUBSCRIBE. // Expiry causes a reconnect to prevent stale connections. // Zero defaults to one second. CommandTimeout time.Duration // Limit the duration for network connection establishment. Expiry // causes an abort plus retry. See net.Dialer Timeout for details. // Zero defaults to one second. DialTimeout time.Duration // AUTH when not nil. Password []byte }
ListenerConfig defines a Listener setup.
type SETOptions ¶ added in v1.4.0
type SETOptions struct { // Composotion of NX, XX, EX or PX. The combinations // (NX | XX) and (EX | PX) are rejected to prevent // mistakes. Flags uint // The value is truncated to seconds with the EX flag, // or milliseconds with PX. Non-zero values without any // expiry Flags are rejected to prevent mistakes. Expire time.Duration }
SETOptions are extra arguments for the SET command.
type ServerError ¶
type ServerError string
ServerError is a response from Redis.
func (ServerError) Prefix ¶
func (e ServerError) Prefix() string
Prefix returns the first word, which represents the error kind.