redis

package module
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Mar 14, 2023 License: CC0-1.0 Imports: 11 Imported by: 2

README

About

… a Redis client for the Go programming language.

  • Boring API with full type-safety
  • Automatic pipelining on concurrency
  • High throughput despite low footprint
  • Efficient OS and network utilization
  • Robust error recovery

Network I/O is executed in the same goroutine that invoked the Client. There is no internal error reporting/logging by design.

This is free and unencumbered software released into the public domain.

Go Reference Build Status

Synchonous Command Execution

// Redis is a thread-safe connection establishment.
var Redis = redis.NewClient("rds1.example.com", time.Second/2, 0)

// Grow adds a string to a list.
func Grow() {
	newLen, err := Redis.RPUSHString("demo_list", "hello")
	if err != nil {
		log.Print("demo_list update error: ", err)
		return
	}
	log.Printf("demo_list has %d elements", newLen)
}

// Ping pushes a message to a publish–subscribe channel.
func Ping() {
	clientCount, err := Redis.PUBLISHString("demo_channel", "ping")
	if err != nil {
		log.Print("demo_channel publish error: ", err)
		return
	}
	log.Printf("pinged %d clients in demo_channel", clientCount)
}

Zero-Copy Pub/Sub Reception

// RedisListener is a thread-safe connection establishment.
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",
})

// Peek listens shortly to a publish–subscribe channel.
func Peek() {
	RedisListener.SUBSCRIBE("demo_channel")
	time.Sleep(time.Second)
	RedisListener.UNSUBSCRIBE("demo_channel")
}

Performance

• Memory allocations are limited to user data only. • Subscription receival does not allocate any memory. • Unix domain sockets make a big improvement over TCP.

Redis.conf needs client-output-buffer-limit pubsub 256mb 256mb 60 to prevent scheduled to be closed ASAP for overcoming of output buffer limits during pub/sub benchmarks.

The following results were measured with Redis version 7, Go version 1.20, on an Apple M1.

name                              TCP time/op    Unix time/op     delta
SimpleString/sequential-8            23.1µs ± 0%     10.2µs ± 0%     -55.73%  (p=0.000 n=10+10)
SimpleString/parallel-8              4.13µs ± 0%     1.89µs ± 1%     -54.15%  (p=0.000 n=10+9)
Integer/sequential-8                 22.3µs ± 0%     10.3µs ± 0%     -53.93%  (p=0.000 n=10+9)
Integer/parallel-8                   4.00µs ± 0%     1.90µs ± 0%     -52.59%  (p=0.000 n=9+10)
Bulk/8B/sequential/bytes-8           23.1µs ± 0%     10.3µs ± 0%     -55.48%  (p=0.000 n=9+10)
Bulk/8B/sequential/string-8          23.1µs ± 0%     10.3µs ± 0%     -55.44%  (p=0.000 n=10+10)
Bulk/8B/parallel/bytes-8             4.07µs ± 0%     1.91µs ± 0%     -53.10%  (p=0.000 n=10+10)
Bulk/8B/parallel/string-8            4.07µs ± 0%     1.91µs ± 1%     -52.99%  (p=0.000 n=9+10)
Bulk/800B/sequential/bytes-8         23.6µs ± 0%     10.5µs ± 0%     -55.44%  (p=0.000 n=9+9)
Bulk/800B/sequential/string-8        23.5µs ± 0%     10.5µs ± 0%     -55.44%  (p=0.000 n=10+10)
Bulk/800B/parallel/bytes-8           4.19µs ± 0%     2.47µs ± 1%     -40.97%  (p=0.000 n=10+10)
Bulk/800B/parallel/string-8          4.22µs ± 0%     3.17µs ± 0%     -24.86%  (p=0.000 n=10+10)
Bulk/24000B/sequential/bytes-8       30.0µs ± 1%     34.8µs ± 0%     +16.00%  (p=0.000 n=10+9)
Bulk/24000B/sequential/string-8      33.8µs ± 0%     39.0µs ± 0%     +15.53%  (p=0.000 n=9+10)
Bulk/24000B/parallel/bytes-8         8.60µs ± 1%    28.53µs ± 0%    +231.91%  (p=0.000 n=10+10)
Bulk/24000B/parallel/string-8        13.9µs ± 2%     31.6µs ± 0%    +126.55%  (p=0.000 n=9+10)
Array/1×8B/sequential/bytes-8        23.5µs ± 0%     10.5µs ± 0%     -55.41%  (p=0.000 n=10+10)
Array/1×8B/sequential/string-8       23.4µs ± 0%     10.4µs ± 0%     -55.40%  (p=0.000 n=10+10)
Array/1×8B/parallel/bytes-8          4.21µs ± 0%     1.93µs ± 1%     -54.05%  (p=0.000 n=10+10)
Array/1×8B/parallel/string-8         4.20µs ± 0%     1.93µs ± 0%     -53.98%  (p=0.000 n=9+10)
Array/12×8B/sequential/bytes-8       24.6µs ± 0%     11.8µs ± 0%     -52.25%  (p=0.000 n=10+10)
Array/12×8B/sequential/string-8      24.4µs ± 1%     11.6µs ± 0%     -52.29%  (p=0.000 n=9+7)
Array/12×8B/parallel/bytes-8         4.41µs ± 1%     2.62µs ± 0%     -40.48%  (p=0.000 n=9+10)
Array/12×8B/parallel/string-8        4.54µs ± 1%     2.59µs ± 3%     -43.05%  (p=0.000 n=10+10)
Array/144×8B/sequential/bytes-8      35.8µs ± 0%     24.3µs ± 0%     -31.97%  (p=0.000 n=9+8)
Array/144×8B/sequential/string-8     34.8µs ± 0%     23.4µs ± 0%     -32.58%  (p=0.000 n=9+10)
Array/144×8B/parallel/bytes-8        13.6µs ± 2%     11.5µs ± 0%     -14.86%  (p=0.000 n=10+9)
Array/144×8B/parallel/string-8       13.0µs ± 1%     10.1µs ± 0%     -22.12%  (p=0.000 n=10+10)
PubSub/8B/1publishers-8              4.71µs ± 1%     2.05µs ±12%     -56.56%  (p=0.000 n=10+10)
PubSub/8B/2publishers-8              2.70µs ± 1%     1.90µs ± 9%     -29.74%  (p=0.000 n=9+10)
PubSub/8B/16publishers-8             1.77µs ± 1%     1.57µs ± 7%     -11.01%  (p=0.000 n=9+10)
PubSub/800B/1publishers-8            4.93µs ± 1%     2.15µs ± 1%     -56.30%  (p=0.000 n=10+8)
PubSub/800B/2publishers-8            2.85µs ± 0%     1.83µs ± 5%     -35.94%  (p=0.000 n=9+9)
PubSub/800B/16publishers-8           1.83µs ± 1%     1.62µs ± 1%     -11.51%  (p=0.000 n=10+9)
PubSub/24000B/1publishers-8          10.7µs ± 3%     36.9µs ±15%    +244.31%  (p=0.000 n=10+10)
PubSub/24000B/2publishers-8          10.9µs ± 1%     36.4µs ±16%    +232.35%  (p=0.000 n=10+10)
PubSub/24000B/16publishers-8         11.1µs ± 1%     36.5µs ±15%    +228.50%  (p=0.000 n=8+10)

name                              TCP speed      Unix speed       delta
Bulk/8B/sequential/bytes-8          350kB/s ± 0%    780kB/s ± 0%    +122.86%  (p=0.000 n=10+10)
Bulk/8B/sequential/string-8         350kB/s ± 0%    780kB/s ± 0%    +122.86%  (p=0.000 n=10+10)
Bulk/8B/parallel/bytes-8           1.96MB/s ± 0%   4.19MB/s ± 1%    +113.35%  (p=0.000 n=10+10)
Bulk/8B/parallel/string-8          1.97MB/s ± 0%   4.18MB/s ± 1%    +112.69%  (p=0.000 n=9+10)
Bulk/800B/sequential/bytes-8       34.0MB/s ± 0%   76.2MB/s ± 0%    +124.40%  (p=0.000 n=9+9)
Bulk/800B/sequential/string-8      34.0MB/s ± 0%   76.3MB/s ± 0%    +124.39%  (p=0.000 n=10+10)
Bulk/800B/parallel/bytes-8          191MB/s ± 0%    323MB/s ± 1%     +69.40%  (p=0.000 n=10+10)
Bulk/800B/parallel/string-8         189MB/s ± 0%    252MB/s ± 0%     +33.08%  (p=0.000 n=10+10)
Bulk/24000B/sequential/bytes-8      800MB/s ± 1%    690MB/s ± 0%     -13.80%  (p=0.000 n=10+9)
Bulk/24000B/sequential/string-8     711MB/s ± 0%    615MB/s ± 0%     -13.44%  (p=0.000 n=9+10)
Bulk/24000B/parallel/bytes-8       2.79GB/s ± 1%   0.84GB/s ± 0%     -69.87%  (p=0.000 n=10+10)
Bulk/24000B/parallel/string-8      1.72GB/s ± 2%   0.76GB/s ± 0%     -55.86%  (p=0.000 n=9+10)
Array/1×8B/sequential/bytes-8       340kB/s ± 0%    763kB/s ± 1%    +124.41%  (p=0.000 n=10+10)
Array/1×8B/sequential/string-8      340kB/s ± 0%    770kB/s ± 0%    +126.47%  (p=0.000 n=10+8)
Array/1×8B/parallel/bytes-8        1.90MB/s ± 0%   4.14MB/s ± 1%    +117.84%  (p=0.000 n=9+10)
Array/1×8B/parallel/string-8       1.90MB/s ± 0%   4.14MB/s ± 0%    +117.28%  (p=0.000 n=9+9)
Array/12×8B/sequential/bytes-8     3.90MB/s ± 0%   8.16MB/s ± 0%    +109.40%  (p=0.000 n=10+9)
Array/12×8B/sequential/string-8    3.93MB/s ± 0%   8.25MB/s ± 0%    +109.75%  (p=0.000 n=8+7)
Array/12×8B/parallel/bytes-8       21.8MB/s ± 1%   36.6MB/s ± 0%     +68.01%  (p=0.000 n=9+10)
Array/12×8B/parallel/string-8      21.1MB/s ± 1%   37.1MB/s ± 3%     +75.62%  (p=0.000 n=10+10)
Array/144×8B/sequential/bytes-8    32.2MB/s ± 0%   47.3MB/s ± 0%     +47.00%  (p=0.000 n=9+8)
Array/144×8B/sequential/string-8   33.1MB/s ± 0%   49.2MB/s ± 0%     +48.34%  (p=0.000 n=9+10)
Array/144×8B/parallel/bytes-8      84.9MB/s ± 2%   99.8MB/s ± 0%     +17.45%  (p=0.000 n=10+9)
Array/144×8B/parallel/string-8     88.5MB/s ± 1%  113.6MB/s ± 0%     +28.40%  (p=0.000 n=10+10)
PubSub/8B/1publishers-8            1.70MB/s ± 2%   3.92MB/s ±11%    +131.00%  (p=0.000 n=10+10)
PubSub/8B/2publishers-8            2.96MB/s ± 1%   4.22MB/s ± 9%     +42.74%  (p=0.000 n=9+10)
PubSub/8B/16publishers-8           4.53MB/s ± 1%   5.09MB/s ± 8%     +12.44%  (p=0.000 n=9+10)
PubSub/800B/1publishers-8           162MB/s ± 1%    372MB/s ± 1%    +128.82%  (p=0.000 n=10+8)
PubSub/800B/2publishers-8           280MB/s ± 0%    434MB/s ± 9%     +54.67%  (p=0.000 n=9+10)
PubSub/800B/16publishers-8          437MB/s ± 1%    494MB/s ± 1%     +13.00%  (p=0.000 n=10+9)
PubSub/24000B/1publishers-8        2.24GB/s ± 3%   0.65GB/s ±14%     -70.78%  (p=0.000 n=10+10)
PubSub/24000B/2publishers-8        2.19GB/s ± 1%   0.67GB/s ±15%     -69.65%  (p=0.000 n=10+10)
PubSub/24000B/16publishers-8       2.16GB/s ± 1%   0.66GB/s ±14%     -69.36%  (p=0.000 n=8+10)

name                              TCP ns/delay   Unix ns/delay    delta
PubSub/8B/1publishers-8               35.8k ± 1%     60.0k ±117%        ~     (p=0.481 n=10+10)
PubSub/8B/2publishers-8               39.7k ± 1%   1289.5k ±139%   +3149.67%  (p=0.034 n=8+10)
PubSub/8B/16publishers-8               225k ± 1%      836k ±133%    +271.99%  (p=0.034 n=8+10)
PubSub/800B/1publishers-8             37.3k ± 1%      15.5k ±16%     -58.38%  (p=0.000 n=9+8)
PubSub/800B/2publishers-8             42.3k ± 0%     86.0k ±152%        ~     (p=0.497 n=9+10)
PubSub/800B/16publishers-8             233k ± 0%       266k ±24%     +14.25%  (p=0.000 n=9+8)
PubSub/24000B/1publishers-8          34.8M ±132%      42.1M ±87%        ~     (p=0.720 n=10+9)
PubSub/24000B/2publishers-8            178k ± 1%     45255k ±77%  +25294.45%  (p=0.000 n=10+9)
PubSub/24000B/16publishers-8          1.42M ± 1%     46.32M ±45%   +3160.60%  (p=0.000 n=8+9)

name                              TCP ns/publish Unix ns/publish  delta
PubSub/8B/1publishers-8               37.7k ± 1%      16.4k ±12%     -56.57%  (p=0.000 n=10+10)
PubSub/8B/2publishers-8               43.2k ± 1%      30.4k ± 9%     -29.73%  (p=0.000 n=9+10)
PubSub/8B/16publishers-8               226k ± 1%       201k ± 8%     -11.00%  (p=0.000 n=9+10)
PubSub/800B/1publishers-8             39.4k ± 1%      17.2k ± 1%     -56.29%  (p=0.000 n=10+8)
PubSub/800B/2publishers-8             45.6k ± 0%      29.2k ± 5%     -35.94%  (p=0.000 n=9+9)
PubSub/800B/16publishers-8             234k ± 1%       207k ± 1%     -11.59%  (p=0.000 n=10+9)
PubSub/24000B/1publishers-8           82.9k ± 6%     285.4k ±15%    +244.32%  (p=0.000 n=10+10)
PubSub/24000B/2publishers-8            175k ± 1%       559k ±28%    +219.06%  (p=0.000 n=10+10)
PubSub/24000B/16publishers-8          1.42M ± 1%      4.49M ±19%    +217.02%  (p=0.000 n=8+10)

Documentation

Overview

Package redis provides access to Redis nodes. See <https://redis.io/topics/introduction> for the concept.

Index

Examples

Constants

View Source 
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

View Source 
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

View Source 
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

View Source 
var ErrClosed = errors.New("redis: connection establishment closed")

ErrClosed signals end-of-life due a call to Close.

Functions

func ParseInt 

func ParseInt(bytes []byte) int64

ParseInt reads bytes as a decimal string without any validation. Empty bytes return zero. The value for any other invalid input is undefined, and may be subject to change in the future.

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 

func NewClient(addr string, commandTimeout, dialTimeout time.Duration) *Client

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 

func (c *Client) APPEND(key string, value []byte) (newLen int64, err error)

APPEND executes <https://redis.io/commands/append>.

func (*Client) APPENDString 

func (c *Client) APPENDString(key, value string) (newLen int64, err error)

APPENDString executes <https://redis.io/commands/append>.

func (*Client) BytesAPPEND 

func (c *Client) BytesAPPEND(key, value []byte) (newLen int64, err error)

BytesAPPEND executes <https://redis.io/commands/append>.

func (*Client) BytesDEL 

func (c *Client) BytesDEL(key []byte) (bool, error)

BytesDEL executes <https://redis.io/commands/del>.

func (*Client) BytesDELArgs added in v1.2.0 

func (c *Client) BytesDELArgs(keys ...[]byte) (int64, error)

BytesDELArgs executes <https://redis.io/commands/del>.

func (*Client) BytesGET 

func (c *Client) BytesGET(key []byte) (value []byte, err error)

BytesGET executes <https://redis.io/commands/get>. The return is nil if key does not exist.

func (*Client) BytesGETRANGE added in v1.4.0 

func (c *Client) BytesGETRANGE(key []byte, start, end int64) ([]byte, error)

BytesGETRANGE executes <https://redis.io/commands/getrange>.

func (*Client) BytesHDEL 

func (c *Client) BytesHDEL(key, field []byte) (bool, error)

BytesHDEL executes <https://redis.io/commands/hdel>.

func (*Client) BytesHDELArgs added in v1.2.0 

func (c *Client) BytesHDELArgs(key []byte, fields ...[]byte) (int64, error)

BytesHDELArgs executes <https://redis.io/commands/hdel>.

func (*Client) BytesHGET 

func (c *Client) BytesHGET(key, field []byte) (value []byte, err error)

BytesHGET executes <https://redis.io/commands/hget>. The return is nil if key does not exist.

func (*Client) BytesHMGET added in v1.2.0 

func (c *Client) BytesHMGET(key []byte, fields ...[]byte) (values [][]byte, err error)

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 

func (c *Client) BytesHMSET(key []byte, fields, values [][]byte) error

BytesHMSET executes <https://redis.io/commands/hmset>.

func (*Client) BytesHSET 

func (c *Client) BytesHSET(key, field, value []byte) (newField bool, err error)

BytesHSET executes <https://redis.io/commands/hset>.

func (*Client) BytesINCR 

func (c *Client) BytesINCR(key []byte) (newValue int64, err error)

BytesINCR executes <https://redis.io/commands/incr>.

func (*Client) BytesINCRBY 

func (c *Client) BytesINCRBY(key []byte, increment int64) (newValue int64, err error)

BytesINCRBY executes <https://redis.io/commands/incrby>.

func (*Client) BytesLINDEX 

func (c *Client) BytesLINDEX(key []byte, index int64) (value []byte, err error)

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 

func (c *Client) BytesLLEN(key []byte) (int64, error)

BytesLLEN executes <https://redis.io/commands/llen>. The return is 0 if key does not exist.

func (*Client) BytesLPOP 

func (c *Client) BytesLPOP(key []byte) (value []byte, err error)

BytesLPOP executes <https://redis.io/commands/lpop>. The return is nil if key does not exist.

func (*Client) BytesLPUSH 

func (c *Client) BytesLPUSH(key, value []byte) (newLen int64, err error)

BytesLPUSH executes <https://redis.io/commands/lpush>.

func (*Client) BytesLRANGE 

func (c *Client) BytesLRANGE(key []byte, start, stop int64) (values [][]byte, err error)

BytesLRANGE executes <https://redis.io/commands/lrange>. The return is empty if key does not exist.

func (*Client) BytesLSET 

func (c *Client) BytesLSET(key []byte, index int64, value []byte) error

BytesLSET executes <https://redis.io/commands/lset>.

func (*Client) BytesLTRIM 

func (c *Client) BytesLTRIM(key []byte, start, stop int64) error

BytesLTRIM executes <https://redis.io/commands/ltrim>.

func (*Client) BytesMGET added in v1.2.0 

func (c *Client) BytesMGET(keys ...[]byte) (values [][]byte, err error)

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 

func (c *Client) BytesMOVE(key []byte, db int64) (bool, error)

BytesMOVE executes <https://redis.io/commands/move>.

func (*Client) BytesMSET added in v1.2.0 

func (c *Client) BytesMSET(keys, values [][]byte) error

BytesMSET executes <https://redis.io/commands/mset>.

func (*Client) BytesRPOP 

func (c *Client) BytesRPOP(key []byte) (value []byte, err error)

BytesRPOP executes <https://redis.io/commands/rpop>. The return is nil if key does not exist.

func (*Client) BytesRPUSH 

func (c *Client) BytesRPUSH(key, value []byte) (newLen int64, err error)

BytesRPUSH executes <https://redis.io/commands/rpush>.

func (*Client) BytesSET 

func (c *Client) BytesSET(key, value []byte) error

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 

func (c *Client) BytesSTRLEN(key []byte) (int64, error)

BytesSTRLEN executes <https://redis.io/commands/strlen>.

func (*Client) Close added in v1.2.0 

func (c *Client) Close() error

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 

func (c *Client) DEL(key string) (bool, error)

DEL executes <https://redis.io/commands/del>.

func (*Client) DELArgs added in v1.2.0 

func (c *Client) DELArgs(keys ...string) (int64, error)

DELArgs executes <https://redis.io/commands/del>.

func (*Client) FLUSHALL added in v1.1.0 

func (c *Client) FLUSHALL(async bool) error

FLUSHALL executes <https://redis.io/commands/flushall>.

func (*Client) FLUSHDB added in v1.1.0 

func (c *Client) FLUSHDB(async bool) error

FLUSHDB executes <https://redis.io/commands/flushdb>.

func (*Client) GET 

func (c *Client) GET(key string) (value []byte, err error)

GET executes <https://redis.io/commands/get>. The return is nil if key does not exist.

func (*Client) GETRANGE added in v1.4.0 

func (c *Client) GETRANGE(key string, start, end int64) ([]byte, error)

GETRANGE executes <https://redis.io/commands/getrange>.

func (*Client) GETRANGEString added in v1.4.0 

func (c *Client) GETRANGEString(key string, start, end int64) (string, error)

GETRANGEString executes <https://redis.io/commands/getrange>.

func (*Client) GETString added in v1.4.0 

func (c *Client) GETString(key string) (value string, ok bool, err error)

GETString executes <https://redis.io/commands/get>. Boolean ok is false if key does not exist.

func (*Client) HDEL 

func (c *Client) HDEL(key, field string) (bool, error)

HDEL executes <https://redis.io/commands/hdel>.

func (*Client) HDELArgs added in v1.2.0 

func (c *Client) HDELArgs(key string, fields ...string) (int64, error)

HDELArgs executes <https://redis.io/commands/hdel>.

func (*Client) HGET 

func (c *Client) HGET(key, field string) (value []byte, err error)

HGET executes <https://redis.io/commands/hget>. The return is nil if key does not exist.

func (*Client) HGETString added in v1.4.0 

func (c *Client) HGETString(key, field string) (value string, ok bool, err error)

HGETString executes <https://redis.io/commands/hget>. Boolean ok is false if key does not exist.

func (*Client) HMGET added in v1.2.0 

func (c *Client) HMGET(key string, fields ...string) (values [][]byte, err error)

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 

func (c *Client) HMGETString(key string, fields ...string) (values []string, err error)

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 

func (c *Client) HMSET(key string, fields []string, values [][]byte) error

HMSET executes <https://redis.io/commands/hmset>.

func (*Client) HMSETString added in v1.2.0 

func (c *Client) HMSETString(key string, fields, values []string) error

HMSETString executes <https://redis.io/commands/hmset>.

func (*Client) HSET 

func (c *Client) HSET(key, field string, value []byte) (newField bool, err error)

HSET executes <https://redis.io/commands/hset>.

func (*Client) HSETString 

func (c *Client) HSETString(key, field, value string) (updated bool, err error)

HSETString executes <https://redis.io/commands/hset>.

func (*Client) INCR 

func (c *Client) INCR(key string) (newValue int64, err error)

INCR executes <https://redis.io/commands/incr>.

func (*Client) INCRBY 

func (c *Client) INCRBY(key string, increment int64) (newValue int64, err error)

INCRBY executes <https://redis.io/commands/incrby>.

func (*Client) LINDEX 

func (c *Client) LINDEX(key string, index int64) (value []byte, err error)

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 

func (c *Client) LINDEXString(key string, index int64) (value string, ok bool, err error)

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 

func (c *Client) LLEN(key string) (int64, error)

LLEN executes <https://redis.io/commands/llen>. The return is 0 if key does not exist.

func (*Client) LPOP 

func (c *Client) LPOP(key string) (value []byte, err error)

LPOP executes <https://redis.io/commands/lpop>. The return is nil if key does not exist.

func (*Client) LPOPString added in v1.4.0 

func (c *Client) LPOPString(key string) (value string, ok bool, err error)

LPOPString executes <https://redis.io/commands/lpop>. Boolean ok is false if key does not exist.

func (*Client) LPUSH 

func (c *Client) LPUSH(key string, value []byte) (newLen int64, err error)

LPUSH executes <https://redis.io/commands/lpush>.

func (*Client) LPUSHString 

func (c *Client) LPUSHString(key, value string) (newLen int64, err error)

LPUSHString executes <https://redis.io/commands/lpush>.

func (*Client) LRANGE 

func (c *Client) LRANGE(key string, start, stop int64) (values [][]byte, err error)

LRANGE executes <https://redis.io/commands/lrange>. The return is empty if key does not exist.

func (*Client) LRANGEString added in v1.4.0 

func (c *Client) LRANGEString(key string, start, stop int64) (values []string, err error)

LRANGEString executes <https://redis.io/commands/lrange>. The return is empty if key does not exist.

func (*Client) LSET 

func (c *Client) LSET(key string, index int64, value []byte) error

LSET executes <https://redis.io/commands/lset>.

func (*Client) LSETString 

func (c *Client) LSETString(key string, index int64, value string) error

LSETString executes <https://redis.io/commands/lset>.

func (*Client) LTRIM 

func (c *Client) LTRIM(key string, start, stop int64) error

LTRIM executes <https://redis.io/commands/ltrim>.

func (*Client) MGET added in v1.2.0 

func (c *Client) MGET(keys ...string) (values [][]byte, err error)

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 

func (c *Client) MGETString(keys ...string) (values []string, err error)

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 

func (c *Client) MOVE(key string, db int64) (bool, error)

MOVE executes <https://redis.io/commands/move>.

func (*Client) MSET added in v1.2.0 

func (c *Client) MSET(keys []string, values [][]byte) error

MSET executes <https://redis.io/commands/mset>.

func (*Client) MSETString added in v1.2.0 

func (c *Client) MSETString(keys, values []string) error

MSETString executes <https://redis.io/commands/mset>.

func (*Client) PUBLISH added in v1.4.0 

func (c *Client) PUBLISH(channel string, message []byte) (clientCount int64, err error)

PUBLISH executes <https://redis.io/commands/publish>.

func (*Client) PUBLISHString added in v1.4.0 

func (c *Client) PUBLISHString(channel, message string) (clientCount int64, err error)

PUBLISHString executes <https://redis.io/commands/publish>.

func (*Client) RPOP 

func (c *Client) RPOP(key string) (value []byte, err error)

RPOP executes <https://redis.io/commands/rpop>. The return is nil if key does not exist.

func (*Client) RPOPString added in v1.4.0 

func (c *Client) RPOPString(key string) (value string, ok bool, err error)

RPOPString executes <https://redis.io/commands/rpop>. Boolean ok is false if key does not exist.

func (*Client) RPUSH 

func (c *Client) RPUSH(key string, value []byte) (newLen int64, err error)

RPUSH executes <https://redis.io/commands/rpush>.

func (*Client) RPUSHString 

func (c *Client) RPUSHString(key, value string) (newLen int64, err error)

RPUSHString executes <https://redis.io/commands/rpush>.

func (*Client) SELECT deprecated added in v1.1.0 

func (c *Client) SELECT(db int64) error

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 

func (c *Client) SET(key string, value []byte) error

SET executes <https://redis.io/commands/set>.

func (*Client) SETString 

func (c *Client) SETString(key, value string) error

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 

func (c *Client) SETWithOptions(key string, value []byte, o SETOptions) (bool, error)

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.

func (*Client) STRLEN added in v1.4.0 

func (c *Client) STRLEN(key string) (int64, error)

STRLEN executes <https://redis.io/commands/strlen>.

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 

func (l *Listener) Close() error

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 

func (l *Listener) SUBSCRIBE(channels ...string)

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 

func (l *Listener) UNSUBSCRIBE(channels ...string)

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) Error 

func (e ServerError) Error() string

Error honors the error interface.

func (ServerError) Prefix 

func (e ServerError) Prefix() string

Prefix returns the first word, which represents the error kind.

Source Files

View all Source files

Directories

Path Synopsis
cmd
reget

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.