redis

package
v1.9.2 Latest Latest
Warning

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

 Go to latest Published: Feb 25, 2024 License: Apache-2.0 Imports: 20 Imported by: 7,731

Documentation

Overview

Package redis is a client for the Redis database.

The Redigo FAQ (https://github.com/gomodule/redigo/wiki/FAQ) contains more documentation about this package.

Connections

The Conn interface is the primary interface for working with Redis. Applications create connections by calling the Dial, DialWithTimeout or NewConn functions. In the future, functions will be added for creating sharded and other types of connections.

The application must call the connection Close method when the application is done with the connection.

Executing Commands

The Conn interface has a generic method for executing Redis commands: 

Do(commandName string, args ...interface{}) (reply interface{}, err error)

The Redis command reference (http://redis.io/commands) lists the available commands. An example of using the Redis APPEND command is: 

n, err := conn.Do("APPEND", "key", "value")

The Do method converts command arguments to bulk strings for transmission to the server as follows: 

Go Type                 Conversion
[]byte                  Sent as is
string                  Sent as is
int, int64              strconv.FormatInt(v)
float64                 strconv.FormatFloat(v, 'g', -1, 64)
bool                    true -> "1", false -> "0"
nil                     ""
all other types         fmt.Fprint(w, v)

Redis command reply types are represented using the following Go types: 

Redis type              Go type
error                   redis.Error
integer                 int64
simple string           string
bulk string             []byte or nil if value not present.
array                   []interface{} or nil if value not present.

Use type assertions or the reply helper functions to convert from interface{} to the specific Go type for the command result.

Pipelining

Connections support pipelining using the Send, Flush and Receive methods. 

Send(commandName string, args ...interface{}) error
Flush() error
Receive() (reply interface{}, err error)

Send writes the command to the connection's output buffer. Flush flushes the connection's output buffer to the server. Receive reads a single reply from the server. The following example shows a simple pipeline. 

c.Send("SET", "foo", "bar")
c.Send("GET", "foo")
c.Flush()
c.Receive() // reply from SET
v, err = c.Receive() // reply from GET

The Do method combines the functionality of the Send, Flush and Receive methods. The Do method starts by writing the command and flushing the output buffer. Next, the Do method receives all pending replies including the reply for the command just sent by Do. If any of the received replies is an error, then Do returns the error. If there are no errors, then Do returns the last reply. If the command argument to the Do method is "", then the Do method will flush the output buffer and receive pending replies without sending a command.

Use the Send and Do methods to implement pipelined transactions. 

c.Send("MULTI")
c.Send("INCR", "foo")
c.Send("INCR", "bar")
r, err := c.Do("EXEC")
fmt.Println(r) // prints [1, 1]

Concurrency

Connections support one concurrent caller to the Receive method and one concurrent caller to the Send and Flush methods. No other concurrency is supported including concurrent calls to the Do and Close methods.

For full concurrent access to Redis, use the thread-safe Pool to get, use and release a connection from within a goroutine. Connections returned from a Pool have the concurrency restrictions described in the previous paragraph.

Publish and Subscribe

Use the Send, Flush and Receive methods to implement Pub/Sub subscribers. 

c.Send("SUBSCRIBE", "example")
c.Flush()
for {
    reply, err := c.Receive()
    if err != nil {
        return err
    }
    // process pushed message
}

The PubSubConn type wraps a Conn with convenience methods for implementing subscribers. The Subscribe, PSubscribe, Unsubscribe and PUnsubscribe methods send and flush a subscription management command. The receive method converts a pushed message to convenient types for use in a type switch. 

psc := redis.PubSubConn{Conn: c}
psc.Subscribe("example")
for {
    switch v := psc.Receive().(type) {
    case redis.Message:
        fmt.Printf("%s: message: %s\n", v.Channel, v.Data)
    case redis.Subscription:
        fmt.Printf("%s: %s %d\n", v.Channel, v.Kind, v.Count)
    case error:
        return v
    }
}

Reply Helpers

The Bool, Int, Bytes, String, Strings and Values functions convert a reply to a value of a specific type. To allow convenient wrapping of calls to the connection Do and Receive methods, the functions take a second argument of type error. If the error is non-nil, then the helper function returns the error. If the error is nil, the function converts the reply to the specified type: 

exists, err := redis.Bool(c.Do("EXISTS", "foo"))
if err != nil {
    // handle error return from c.Do or type conversion error.
}

The Scan function converts elements of a array reply to Go types: 

var value1 int
var value2 string
reply, err := redis.Values(c.Do("MGET", "key1", "key2"))
if err != nil {
    // handle error
}
 if _, err := redis.Scan(reply, &value1, &value2); err != nil {
    // handle error
}

Errors

Connection methods return error replies from the server as type redis.Error.

Call the connection Err() method to determine if the connection encountered non-recoverable error such as a network error or protocol parsing error. If Err() returns a non-nil value, then the connection is not usable and should be closed.

Example (Zpop)

This example implements ZPOP as described at http://redis.io/topics/transactions using WATCH/MULTI/EXEC and scripting. 

package main

import (
	"fmt"

	"github.com/gomodule/redigo/redis"
)

// zpop pops a value from the ZSET key using WATCH/MULTI/EXEC commands.
func zpop(c redis.Conn, key string) (result string, err error) {

	defer func() {
		// Return connection to normal state on error.
		if err != nil {
			c.Do("DISCARD") // nolint: errcheck
		}
	}()

	// Loop until transaction is successful.
	for {
		if _, err := c.Do("WATCH", key); err != nil {
			return "", err
		}

		members, err := redis.Strings(c.Do("ZRANGE", key, 0, 0))
		if err != nil {
			return "", err
		}
		if len(members) != 1 {
			return "", redis.ErrNil
		}

		if err = c.Send("MULTI"); err != nil {
			return "", err
		}
		if err = c.Send("ZREM", key, members[0]); err != nil {
			return "", err
		}
		queued, err := c.Do("EXEC")
		if err != nil {
			return "", err
		}

		if queued != nil {
			result = members[0]
			break
		}
	}

	return result, nil
}

// zpopScript pops a value from a ZSET.
var zpopScript = redis.NewScript(1, `
    local r = redis.call('ZRANGE', KEYS[1], 0, 0)
    if r ~= nil then
        r = r[1]
        redis.call('ZREM', KEYS[1], r)
    end
    return r
`)

// This example implements ZPOP as described at
// http://redis.io/topics/transactions using WATCH/MULTI/EXEC and scripting.
func main() {
	c, err := dial()
	if err != nil {
		fmt.Println(err)
		return
	}
	defer c.Close()

	// Add test data using a pipeline.

	for i, member := range []string{"red", "blue", "green"} {
		if err = c.Send("ZADD", "zset", i, member); err != nil {
			fmt.Println(err)
			return
		}
	}

	if _, err := c.Do(""); err != nil {
		fmt.Println(err)
		return
	}

	// Pop using WATCH/MULTI/EXEC

	v, err := zpop(c, "zset")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(v)

	// Pop using a script.

	v, err = redis.String(zpopScript.Do(c, "zset"))
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(v)

}

Output:

red
blue

Index

Examples

Constants

This section is empty.

Variables

View Source 
var ErrNil = errors.New("redigo: nil returned")

ErrNil indicates that a reply value is nil.

View Source 
var ErrPoolExhausted = errors.New("redigo: connection pool exhausted")

ErrPoolExhausted is returned from a pool connection method (Do, Send, Receive, Flush, Err) when the maximum number of database connections in the pool has been reached.

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
Example 
package main

import (
	"fmt"

	"github.com/gomodule/redigo/redis"
)

// dial wraps DialDefaultServer() with a more suitable function name for examples.
func dial() (redis.Conn, error) {
	return redis.DialDefaultServer()
}

func main() {
	c, err := dial()
	if err != nil {
		fmt.Println(err)
		return
	}
	defer c.Close()

	if _, err = c.Do("SET", "foo", 1); err != nil {
		fmt.Println(err)
		return
	}
	exists, err := redis.Bool(c.Do("EXISTS", "foo"))
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Printf("%#v\n", exists)
}

Output:

true

func ByteSlices 

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

ByteSlices is a helper that converts an array command reply to a [][]byte. If err is not equal to nil, then ByteSlices returns nil, err. Nil array items are stay nil. ByteSlices returns an error if an array item is not a bulk string or nil.

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 DoContext added in v1.8.6 

func DoContext(c Conn, ctx context.Context, cmd string, args ...interface{}) (interface{}, error)

DoContext sends a command to server and returns the received reply. min(ctx,DialReadTimeout()) will be used as the deadline. The connection will be closed if DialReadTimeout() timeout or ctx timeout or ctx canceled when this function is running. DialReadTimeout() timeout return err can be checked by errors.Is(err, os.ErrDeadlineExceeded). ctx timeout return err context.DeadlineExceeded. ctx canceled return err context.Canceled.

func DoWithTimeout 

func DoWithTimeout(c Conn, timeout time.Duration, cmd string, args ...interface{}) (interface{}, error)

DoWithTimeout executes a Redis command with the specified read timeout. If the connection does not satisfy the ConnWithTimeout interface, then an error is returned.

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 a float64 as follows: 

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

func Float64Map added in v1.8.9 

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

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

func Float64s 

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

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

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
Example 
package main

import (
	"fmt"

	"github.com/gomodule/redigo/redis"
)

// dial wraps DialDefaultServer() with a more suitable function name for examples.
func dial() (redis.Conn, error) {
	return redis.DialDefaultServer()
}

func main() {
	c, err := dial()
	if err != nil {
		fmt.Println(err)
		return
	}
	defer c.Close()

	_, err = c.Do("SET", "k1", 1)
	if err != nil {
		fmt.Println(err)
		return
	}
	n, err := redis.Int(c.Do("GET", "k1"))
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Printf("%#v\n", n)
	n, err = redis.Int(c.Do("INCR", "k1"))
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Printf("%#v\n", n)
}

Output:

1
2

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 Int64 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 Int64Map 

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

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

func Int64s 

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

Int64s is a helper that converts an array command reply to a []int64. If err is not equal to nil, then Int64s returns nil, err. Nil array items are stay nil. Int64s returns an error if an array item is not a bulk string or nil.

func IntMap 

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

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

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. Nil array items are stay nil. Ints returns an error if an array item is not a bulk string or nil.

Example 
package main

import (
	"fmt"

	"github.com/gomodule/redigo/redis"
)

// dial wraps DialDefaultServer() with a more suitable function name for examples.
func dial() (redis.Conn, error) {
	return redis.DialDefaultServer()
}

func main() {
	c, err := dial()
	if err != nil {
		fmt.Println(err)
		return
	}
	defer c.Close()

	_, err = c.Do("SADD", "set_with_integers", 4, 5, 6)
	if err != nil {
		fmt.Println(err)
		return
	}
	ints, err := redis.Ints(c.Do("SMEMBERS", "set_with_integers"))
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Printf("%#v\n", ints)
}

Output:

[]int{4, 5, 6}

func MultiBulk deprecated 

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

MultiBulk is a helper that converts an array command reply to a []interface{}.

Deprecated: Use Values instead.

func Positions 

func Positions(result interface{}, err error) ([]*[2]float64, error)

Positions is a helper that converts an array of positions (lat, long) into a [][2]float64. The GEOPOS command returns replies in this format.

func ReceiveContext added in v1.8.6 

func ReceiveContext(c Conn, ctx context.Context) (interface{}, error)

ReceiveContext receives a single reply from the Redis server. min(ctx,DialReadTimeout()) will be used as the deadline. The connection will be closed if DialReadTimeout() timeout or ctx timeout or ctx canceled when this function is running. DialReadTimeout() timeout return err can be checked by strings.Contains(e.Error(), "io/timeout"). ctx timeout return err context.DeadlineExceeded. ctx canceled return err context.Canceled.

func ReceiveWithTimeout 

func ReceiveWithTimeout(c Conn, timeout time.Duration) (interface{}, error)

ReceiveWithTimeout receives a reply with the specified read timeout. If the connection does not satisfy the ConnWithTimeout interface, then an error is returned.

func Scan 

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

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

Scan uses RedisScan if available otherwise:

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.

Example 
c, err := dial()
if err != nil {
	fmt.Println(err)
	return
}
defer c.Close()

if err = c.Send("HMSET", "album:1", "title", "Red", "rating", 5); err != nil {
	fmt.Println(err)
	return
}
if err = c.Send("HMSET", "album:2", "title", "Earthbound", "rating", 1); err != nil {
	fmt.Println(err)
	return
}
if err = c.Send("HMSET", "album:3", "title", "Beat"); err != nil {
	fmt.Println(err)
	return
}
if err = c.Send("LPUSH", "albums", "1"); err != nil {
	fmt.Println(err)
	return
}
if err = c.Send("LPUSH", "albums", "2"); err != nil {
	fmt.Println(err)
	return
}
if err = c.Send("LPUSH", "albums", "3"); err != nil {
	fmt.Println(err)
	return
}
values, err := redis.Values(c.Do("SORT", "albums",
	"BY", "album:*->rating",
	"GET", "album:*->title",
	"GET", "album:*->rating"))
if err != nil {
	fmt.Println(err)
	return
}

for len(values) > 0 {
	var title string
	rating := -1 // initialize to illegal value to detect nil.
	values, err = redis.Scan(values, &title, &rating)
	if err != nil {
		fmt.Println(err)
		return
	}
	if rating == -1 {
		fmt.Println(title, "not-rated")
	} else {
		fmt.Println(title, rating)
	}
}

Output:

Beat not-rated
Earthbound 1
Red 5

func ScanSlice 

func ScanSlice(src []interface{}, dest interface{}, fieldNames ...string) error

ScanSlice scans src to the slice pointed to by dest.

If the target is a slice of types which implement Scanner then the custom RedisScan method is used otherwise the following rules apply:

The elements in the dest slice must be integer, float, boolean, string, struct or pointer to struct values.

Struct fields must be integer, float, boolean or string values. All struct fields are used unless a subset is specified using fieldNames.

Example 
c, err := dial()
if err != nil {
	fmt.Println(err)
	return
}
defer c.Close()

if err = c.Send("HMSET", "album:1", "title", "Red", "rating", 5); err != nil {
	fmt.Println(err)
	return
}
if err = c.Send("HMSET", "album:2", "title", "Earthbound", "rating", 1); err != nil {
	fmt.Println(err)
	return
}
if err = c.Send("HMSET", "album:3", "title", "Beat", "rating", 4); err != nil {
	fmt.Println(err)
	return
}
if err = c.Send("LPUSH", "albums", "1"); err != nil {
	fmt.Println(err)
	return
}
if err = c.Send("LPUSH", "albums", "2"); err != nil {
	fmt.Println(err)
	return
}
if err = c.Send("LPUSH", "albums", "3"); err != nil {
	fmt.Println(err)
	return
}
values, err := redis.Values(c.Do("SORT", "albums",
	"BY", "album:*->rating",
	"GET", "album:*->title",
	"GET", "album:*->rating"))
if err != nil {
	fmt.Println(err)
	return
}

var albums []struct {
	Title  string
	Rating int
}
if err := redis.ScanSlice(values, &albums); err != nil {
	fmt.Println(err)
	return
}
fmt.Printf("%v\n", albums)

Output:

[{Earthbound 1} {Beat 4} {Red 5}]

func ScanStruct 

func ScanStruct(src []interface{}, dest interface{}) error

ScanStruct scans alternating names and values from src to a struct. The HGETALL and CONFIG GET commands return replies in this format.

ScanStruct uses exported field names to match values in the response. Use 'redis' field tag to override the name: 

Field int `redis:"myName"`

Fields with the tag redis:"-" are ignored.

Each field uses RedisScan if available otherwise: Integer, float, boolean, string and []byte fields are supported. Scan uses the standard strconv package to convert bulk string values to numeric and boolean types.

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

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
Example 
package main

import (
	"fmt"

	"github.com/gomodule/redigo/redis"
)

// dial wraps DialDefaultServer() with a more suitable function name for examples.
func dial() (redis.Conn, error) {
	return redis.DialDefaultServer()
}

func main() {
	c, err := dial()
	if err != nil {
		fmt.Println(err)
		return
	}
	defer c.Close()

	_, err = c.Do("SET", "hello", "world")
	if err != nil {
		fmt.Println(err)
		return
	}
	s, err := redis.String(c.Do("GET", "hello"))
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Printf("%#v\n", s)
}

Output:

"world"

func StringMap 

func StringMap(reply 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 Uint64 

func Uint64(reply interface{}, err error) (uint64, error)

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

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

func Uint64Map added in v1.7.2 

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

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

func Uint64s added in v1.7.2 

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

Uint64s is a helper that converts an array command reply to a []uint64. If err is not equal to nil, then Uint64s returns nil, err. Nil array items are stay nil. Uint64s 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 Args 

type Args []interface{}

Args is a helper for constructing command arguments from structured values.

Example 
c, err := dial()
if err != nil {
	fmt.Println(err)
	return
}
defer c.Close()

var p1, p2 struct {
	Title  string `redis:"title"`
	Author string `redis:"author"`
	Body   string `redis:"body"`
}

p1.Title = "Example"
p1.Author = "Gary"
p1.Body = "Hello"

if _, err := c.Do("HMSET", redis.Args{}.Add("id1").AddFlat(&p1)...); err != nil {
	fmt.Println(err)
	return
}

m := map[string]string{
	"title":  "Example2",
	"author": "Steve",
	"body":   "Map",
}

if _, err := c.Do("HMSET", redis.Args{}.Add("id2").AddFlat(m)...); err != nil {
	fmt.Println(err)
	return
}

for _, id := range []string{"id1", "id2"} {

	v, err := redis.Values(c.Do("HGETALL", id))
	if err != nil {
		fmt.Println(err)
		return
	}

	if err := redis.ScanStruct(v, &p2); err != nil {
		fmt.Println(err)
		return
	}

	fmt.Printf("%+v\n", p2)
}

Output:

{Title:Example Author:Gary Body:Hello}
{Title:Example2 Author:Steve Body:Map}

func (Args) Add 

func (args Args) Add(value ...interface{}) Args

Add returns the result of appending value to args.

func (Args) AddFlat 

func (args Args) AddFlat(v interface{}) Args

AddFlat returns the result of appending the flattened value of v to args.

Maps are flattened by appending the alternating keys and map values to args.

Slices are flattened by appending the slice elements to args.

Structs are flattened by appending the alternating names and values of exported fields to args. If v is a nil struct pointer, then nothing is appended. The 'redis' field tag overrides struct field names. See ScanStruct for more information on the use of the 'redis' field tag.

Other types are appended to args as is. panics if v includes a recursive anonymous struct.

type Argument 

type Argument interface {
	// RedisArg returns a value to be encoded as a bulk string per the
	// conversions listed in the section 'Executing Commands'.
	// Implementations should typically return a []byte or string.
	RedisArg() interface{}
}

Argument is the interface implemented by an object which wants to control how the object is converted to Redis bulk strings.

type Conn 

type Conn interface {
	// Close closes the connection.
	Close() error

	// Err returns a non-nil value when the connection is not usable.
	Err() error

	// Do sends a command to the server and returns the received reply.
	// This function will use the timeout which was set when the connection is created
	Do(commandName string, args ...interface{}) (reply interface{}, err error)

	// Send writes the command to the client's output buffer.
	Send(commandName string, args ...interface{}) error

	// Flush flushes the output buffer to the Redis server.
	Flush() error

	// Receive receives a single reply from the Redis server
	Receive() (reply interface{}, err error)
}

Conn represents a connection to a Redis server.

func Dial 

func Dial(network, address string, options ...DialOption) (Conn, error)

Dial connects to the Redis server at the given network and address using the specified options.

Example

Connect to local instance of Redis running on the default port. 

package main

import (
	"github.com/gomodule/redigo/redis"
)

func main() {
	c, err := redis.Dial("tcp", ":6379")
	if err != nil {
		// handle error
	}
	defer c.Close()
}

Output:
Example (Acl)

Connect to an Redis instance using the Redis ACL system 

package main

import (
	"github.com/gomodule/redigo/redis"
)

func main() {
	c, err := redis.Dial("tcp", "localhost:6379",
		redis.DialUsername("username"),
		redis.DialPassword("password"),
	)
	if err != nil {
		// handle error
	}
	defer c.Close()
}

Output:

func DialContext added in v1.8.2 

func DialContext(ctx context.Context, network, address string, options ...DialOption) (Conn, error)

DialContext connects to the Redis server at the given network and address using the specified options and context.

Example

Connect to local instance of Redis running on the default port using the provided context. 

package main

import (
	"context"

	"github.com/gomodule/redigo/redis"
)

func main() {
	ctx := context.Background()
	c, err := redis.DialContext(ctx, "tcp", ":6379")
	if err != nil {
		// handle error
	}
	defer c.Close()
}

Output:

func DialTimeout deprecated 

func DialTimeout(network, address string, connectTimeout, readTimeout, writeTimeout time.Duration) (Conn, error)

DialTimeout acts like Dial but takes timeouts for establishing the connection to the server, writing a command and reading a reply.

Deprecated: Use Dial with options instead.

func DialURL 

func DialURL(rawurl string, options ...DialOption) (Conn, error)

DialURL wraps DialURLContext using context.Background.

Example

Connect to remote instance of Redis using a URL. 

package main

import (
	"os"

	"github.com/gomodule/redigo/redis"
)

func main() {
	c, err := redis.DialURL(os.Getenv("REDIS_URL"))
	if err != nil {
		// handle connection error
	}
	defer c.Close()
}

Output:

func DialURLContext added in v1.8.6 

func DialURLContext(ctx context.Context, rawurl string, options ...DialOption) (Conn, error)

DialURLContext connects to a Redis server at the given URL using the Redis URI scheme. URLs should follow the draft IANA specification for the scheme (https://www.iana.org/assignments/uri-schemes/prov/redis).

func NewConn 

func NewConn(netConn net.Conn, readTimeout, writeTimeout time.Duration) Conn

NewConn returns a new Redigo connection for the given net connection.

func NewLoggingConn 

func NewLoggingConn(conn Conn, logger *log.Logger, prefix string) Conn

NewLoggingConn returns a logging wrapper around a connection.

func NewLoggingConnFilter 

func NewLoggingConnFilter(conn Conn, logger *log.Logger, prefix string, skip func(cmdName string) bool) Conn

NewLoggingConnFilter returns a logging wrapper around a connection and a filter function.

type ConnWithContext added in v1.8.6 

type ConnWithContext interface {
	Conn

	// DoContext sends a command to server and returns the received reply.
	// min(ctx,DialReadTimeout()) will be used as the deadline.
	// The connection will be closed if DialReadTimeout() timeout or ctx timeout or ctx canceled when this function is running.
	// DialReadTimeout() timeout return err can be checked by errors.Is(err, os.ErrDeadlineExceeded).
	// ctx timeout return err context.DeadlineExceeded.
	// ctx canceled return err context.Canceled.
	DoContext(ctx context.Context, commandName string, args ...interface{}) (reply interface{}, err error)

	// ReceiveContext receives a single reply from the Redis server.
	// min(ctx,DialReadTimeout()) will be used as the deadline.
	// The connection will be closed if DialReadTimeout() timeout or ctx timeout or ctx canceled when this function is running.
	// DialReadTimeout() timeout return err can be checked by errors.Is(err, os.ErrDeadlineExceeded).
	// ctx timeout return err context.DeadlineExceeded.
	// ctx canceled return err context.Canceled.
	ReceiveContext(ctx context.Context) (reply interface{}, err error)
}

ConnWithContext is an optional interface that allows the caller to control the command's life with context.

type ConnWithTimeout 

type ConnWithTimeout interface {
	Conn

	// DoWithTimeout sends a command to the server and returns the received reply.
	// The timeout overrides the readtimeout set when dialing the connection.
	DoWithTimeout(timeout time.Duration, commandName string, args ...interface{}) (reply interface{}, err error)

	// ReceiveWithTimeout receives a single reply from the Redis server.
	// The timeout overrides the readtimeout set when dialing the connection.
	ReceiveWithTimeout(timeout time.Duration) (reply interface{}, err error)
}

ConnWithTimeout is an optional interface that allows the caller to override a connection's default read timeout. This interface is useful for executing the BLPOP, BRPOP, BRPOPLPUSH, XREAD and other commands that block at the server.

A connection's default read timeout is set with the DialReadTimeout dial option. Applications should rely on the default timeout for commands that do not block at the server.

All of the Conn implementations in this package satisfy the ConnWithTimeout interface.

Use the DoWithTimeout and ReceiveWithTimeout helper functions to simplify use of this interface.

type DialOption 

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

DialOption specifies an option for dialing a Redis server.

func DialClientName added in v1.7.2 

func DialClientName(name string) DialOption

DialClientName specifies a client name to be used by the Redis server connection.

func DialConnectTimeout 

func DialConnectTimeout(d time.Duration) DialOption

DialConnectTimeout specifies the timeout for connecting to the Redis server when no DialNetDial option is specified. If no DialConnectTimeout option is specified then the default is 30 seconds.

func DialContextFunc added in v1.8.2 

func DialContextFunc(f func(ctx context.Context, network, addr string) (net.Conn, error)) DialOption

DialContextFunc specifies a custom dial function with context for creating TCP connections, otherwise a net.Dialer customized via the other options is used. DialContextFunc overrides DialConnectTimeout and DialKeepAlive.

func DialDatabase 

func DialDatabase(db int) DialOption

DialDatabase specifies the database to select when dialing a connection.

func DialKeepAlive 

func DialKeepAlive(d time.Duration) DialOption

DialKeepAlive specifies the keep-alive period for TCP connections to the Redis server when no DialNetDial option is specified. If zero, keep-alives are not enabled. If no DialKeepAlive option is specified then the default of 5 minutes is used to ensure that half-closed TCP sessions are detected.

func DialNetDial 

func DialNetDial(dial func(network, addr string) (net.Conn, error)) DialOption

DialNetDial specifies a custom dial function for creating TCP connections, otherwise a net.Dialer customized via the other options is used. DialNetDial overrides DialConnectTimeout and DialKeepAlive.

func DialPassword 

func DialPassword(password string) DialOption

DialPassword specifies the password to use when connecting to the Redis server.

func DialReadTimeout 

func DialReadTimeout(d time.Duration) DialOption

DialReadTimeout specifies the timeout for reading a single command reply.

func DialTLSConfig 

func DialTLSConfig(c *tls.Config) DialOption

DialTLSConfig specifies the config to use when a TLS connection is dialed. Has no effect when not dialing a TLS connection.

func DialTLSHandshakeTimeout added in v1.8.3 

func DialTLSHandshakeTimeout(d time.Duration) DialOption

DialTLSHandshakeTimeout specifies the maximum amount of time waiting to wait for a TLS handshake. Zero means no timeout. If no DialTLSHandshakeTimeout option is specified then the default is 30 seconds.

func DialTLSSkipVerify 

func DialTLSSkipVerify(skip bool) DialOption

DialTLSSkipVerify disables server name verification when connecting over TLS. Has no effect when not dialing a TLS connection.

func DialUseTLS 

func DialUseTLS(useTLS bool) DialOption

DialUseTLS specifies whether TLS should be used when connecting to the server. This option is ignore by DialURL.

func DialUsername added in v1.8.2 

func DialUsername(username string) DialOption

DialUsername specifies the username to use when connecting to the Redis server when Redis ACLs are used. A DialPassword must also be passed otherwise this option will have no effect.

func DialWriteTimeout 

func DialWriteTimeout(d time.Duration) DialOption

DialWriteTimeout specifies the timeout for writing a single command.

type Error 

type Error string

Error represents an error returned in a command reply.

func (Error) Error 

func (err Error) Error() string

type Latency added in v1.8.9 

type Latency struct {
	// Name of the latest latency spike event.
	Name string

	// Time of the latest latency spike for the event.
	Time time.Time

	// Latest is the latest recorded latency for the named event.
	Latest time.Duration

	// Max is the maximum latency for the named event.
	Max time.Duration
}

Latency represents a redis LATENCY LATEST.

func Latencies added in v1.8.9 

func Latencies(result interface{}, err error) ([]Latency, error)

Latencies is a helper that parses the LATENCY LATEST command output and return the slice of Latency values.

type LatencyHistory added in v1.8.9 

type LatencyHistory struct {
	// Time is the unix timestamp at which the event was processed.
	Time time.Time

	// ExecutationTime is the amount of time needed for the command execution.
	ExecutionTime time.Duration
}

LatencyHistory represents a redis LATENCY HISTORY.

func LatencyHistories added in v1.8.9 

func LatencyHistories(result interface{}, err error) ([]LatencyHistory, error)

LatencyHistories is a helper that parse the LATENCY HISTORY command output and returns a LatencyHistory slice.

type Message 

type Message struct {
	// The originating channel.
	Channel string

	// The matched pattern, if any
	Pattern string

	// The message data.
	Data []byte
}

Message represents a message notification.

type Pong 

type Pong struct {
	Data string
}

Pong represents a pubsub pong notification.

type Pool 

type Pool struct {
	// Dial is an application supplied function for creating and configuring a
	// connection.
	//
	// The connection returned from Dial must not be in a special state
	// (subscribed to pubsub channel, transaction started, ...).
	Dial func() (Conn, error)

	// DialContext is an application supplied function for creating and configuring a
	// connection with the given context.
	//
	// The connection returned from DialContext must not be in a special state
	// (subscribed to pubsub channel, transaction started, ...).
	DialContext func(ctx context.Context) (Conn, error)

	// TestOnBorrow is an optional application supplied function for checking
	// the health of an idle connection before the connection is used again by
	// the application. Argument lastUsed is the time when the connection was returned
	// to the pool. If the function returns an error, then the connection is
	// closed.
	TestOnBorrow func(c Conn, lastUsed time.Time) error

	// TestOnBorrowContext is an optional application supplied function
	// for checking the health of an idle connection with the given context
	// before the connection is used again by the application.
	// Argument lastUsed is the time when the connection was returned
	// to the pool. If the function returns an error, then the connection is
	// closed.
	TestOnBorrowContext func(ctx context.Context, c Conn, lastUsed time.Time) error

	// Maximum number of idle connections in the pool.
	MaxIdle int

	// Maximum number of connections allocated by the pool at a given time.
	// When zero, there is no limit on the number of connections in the pool.
	MaxActive int

	// Close connections after remaining idle for this duration. If the value
	// is zero, then idle connections are not closed. Applications should set
	// the timeout to a value less than the server's timeout.
	IdleTimeout time.Duration

	// If Wait is true and the pool is at the MaxActive limit, then Get() waits
	// for a connection to be returned to the pool before returning.
	Wait bool

	// Close connections older than this duration. If the value is zero, then
	// the pool does not close connections based on age.
	MaxConnLifetime time.Duration
	// contains filtered or unexported fields
}

Pool maintains a pool of connections. The application calls the Get method to get a connection from the pool and the connection's Close method to return the connection's resources to the pool.

The following example shows how to use a pool in a web application. The application creates a pool at application startup and makes it available to request handlers using a package level variable. The pool configuration used here is an example, not a recommendation. 

func newPool(addr string) *redis.Pool {
  return &redis.Pool{
    MaxIdle: 3,
    IdleTimeout: 240 * time.Second,
    // Dial or DialContext must be set. When both are set, DialContext takes precedence over Dial.
    Dial: func () (redis.Conn, error) { return redis.Dial("tcp", addr) },
  }
}

var (
  pool *redis.Pool
  redisServer = flag.String("redisServer", ":6379", "")
)

func main() {
  flag.Parse()
  pool = newPool(*redisServer)
  ...
}

A request handler gets a connection from the pool and closes the connection when the handler is done: 

func serveHome(w http.ResponseWriter, r *http.Request) {
    conn := pool.Get()
    defer conn.Close()
    ...
}

Use the Dial function to authenticate connections with the AUTH command or select a database with the SELECT command: 

pool := &redis.Pool{
  // Other pool configuration not shown in this example.
  Dial: func () (redis.Conn, error) {
    c, err := redis.Dial("tcp", server)
    if err != nil {
      return nil, err
    }
    if _, err := c.Do("AUTH", password); err != nil {
      c.Close()
      return nil, err
    }
    if _, err := c.Do("SELECT", db); err != nil {
      c.Close()
      return nil, err
    }
    return c, nil
  },
}

Use the TestOnBorrow function to check the health of an idle connection before the connection is returned to the application. This example PINGs connections that have been idle more than a minute: 

pool := &redis.Pool{
  // Other pool configuration not shown in this example.
  TestOnBorrow: func(c redis.Conn, t time.Time) error {
    if time.Since(t) < time.Minute {
      return nil
    }
    _, err := c.Do("PING")
    return err
  },
}

func NewPool deprecated 

func NewPool(newFn func() (Conn, error), maxIdle int) *Pool

NewPool creates a new pool.

Deprecated: Initialize the Pool directly as shown in the example.

func (*Pool) ActiveCount 

func (p *Pool) ActiveCount() int

ActiveCount returns the number of connections in the pool. The count includes idle connections and connections in use.

func (*Pool) Close 

func (p *Pool) Close() error

Close releases the resources used by the pool.

func (*Pool) Get 

func (p *Pool) Get() Conn

Get gets a connection. The application must close the returned connection. This method always returns a valid connection so that applications can defer error handling to the first use of the connection. If there is an error getting an underlying connection, then the connection Err, Do, Send, Flush and Receive methods return that error.

func (*Pool) GetContext 

func (p *Pool) GetContext(ctx context.Context) (Conn, error)

GetContext gets a connection using the provided context.

The provided Context must be non-nil. If the context expires before the connection is complete, an error is returned. Any expiration on the context will not affect the returned connection.

If the function completes without error, then the application must close the returned connection.

func (*Pool) IdleCount 

func (p *Pool) IdleCount() int

IdleCount returns the number of idle connections in the pool.

func (*Pool) Stats 

func (p *Pool) Stats() PoolStats

Stats returns pool's statistics.

type PoolStats 

type PoolStats struct {
	// ActiveCount is the number of connections in the pool. The count includes
	// idle connections and connections in use.
	ActiveCount int
	// IdleCount is the number of idle connections in the pool.
	IdleCount int

	// WaitCount is the total number of connections waited for.
	// This value is currently not guaranteed to be 100% accurate.
	WaitCount int64

	// WaitDuration is the total time blocked waiting for a new connection.
	// This value is currently not guaranteed to be 100% accurate.
	WaitDuration time.Duration
}

PoolStats contains pool statistics.

type PubSubConn 

type PubSubConn struct {
	Conn Conn
}

PubSubConn wraps a Conn with convenience methods for subscribers.

Example

This example shows how receive pubsub notifications with cancelation and health checks. 

//go:build go1.7
// +build go1.7

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/gomodule/redigo/redis"
)

// listenPubSubChannels listens for messages on Redis pubsub channels. The
// onStart function is called after the channels are subscribed. The onMessage
// function is called for each message.
func listenPubSubChannels(ctx context.Context, redisServerAddr string,
	onStart func() error,
	onMessage func(channel string, data []byte) error,
	channels ...string) error {
	// A ping is set to the server with this period to test for the health of
	// the connection and server.
	const healthCheckPeriod = time.Minute

	c, err := redis.Dial("tcp", redisServerAddr,
		// Read timeout on server should be greater than ping period.
		redis.DialReadTimeout(healthCheckPeriod+10*time.Second),
		redis.DialWriteTimeout(10*time.Second))
	if err != nil {
		return err
	}
	defer c.Close()

	psc := redis.PubSubConn{Conn: c}

	if err := psc.Subscribe(redis.Args{}.AddFlat(channels)...); err != nil {
		return err
	}

	done := make(chan error, 1)

	// Start a goroutine to receive notifications from the server.
	go func() {
		for {
			switch n := psc.Receive().(type) {
			case error:
				done <- n
				return
			case redis.Message:
				if err := onMessage(n.Channel, n.Data); err != nil {
					done <- err
					return
				}
			case redis.Subscription:
				switch n.Count {
				case len(channels):
					// Notify application when all channels are subscribed.
					if err := onStart(); err != nil {
						done <- err
						return
					}
				case 0:
					// Return from the goroutine when all channels are unsubscribed.
					done <- nil
					return
				}
			}
		}
	}()

	ticker := time.NewTicker(healthCheckPeriod)
	defer ticker.Stop()
loop:
	for {
		select {
		case <-ticker.C:
			// Send ping to test health of connection and server. If
			// corresponding pong is not received, then receive on the
			// connection will timeout and the receive goroutine will exit.
			if err = psc.Ping(""); err != nil {
				break loop
			}
		case <-ctx.Done():
			break loop
		case err := <-done:
			// Return error from the receive goroutine.
			return err
		}
	}

	// Signal the receiving goroutine to exit by unsubscribing from all channels.
	if err := psc.Unsubscribe(); err != nil {
		return err
	}

	// Wait for goroutine to complete.
	return <-done
}

func publish() {
	c, err := dial()
	if err != nil {
		fmt.Println(err)
		return
	}
	defer c.Close()

	if _, err = c.Do("PUBLISH", "c1", "hello"); err != nil {
		fmt.Println(err)
		return
	}
	if _, err = c.Do("PUBLISH", "c2", "world"); err != nil {
		fmt.Println(err)
		return
	}
	if _, err = c.Do("PUBLISH", "c1", "goodbye"); err != nil {
		fmt.Println(err)
		return
	}
}

// This example shows how receive pubsub notifications with cancelation and
// health checks.
func main() {
	redisServerAddr, err := serverAddr()
	if err != nil {
		fmt.Println(err)
		return
	}

	ctx, cancel := context.WithCancel(context.Background())

	err = listenPubSubChannels(ctx,
		redisServerAddr,
		func() error {
			// The start callback is a good place to backfill missed
			// notifications. For the purpose of this example, a goroutine is
			// started to send notifications.
			go publish()
			return nil
		},
		func(channel string, message []byte) error {
			fmt.Printf("channel: %s, message: %s\n", channel, message)

			// For the purpose of this example, cancel the listener's context
			// after receiving last message sent by publish().
			if string(message) == "goodbye" {
				cancel()
			}
			return nil
		},
		"c1", "c2")

	if err != nil {
		fmt.Println(err)
		return
	}

}

Output:

channel: c1, message: hello
channel: c2, message: world
channel: c1, message: goodbye

func (PubSubConn) Close 

func (c PubSubConn) Close() error

Close closes the connection.

func (PubSubConn) PSubscribe 

func (c PubSubConn) PSubscribe(channel ...interface{}) error

PSubscribe subscribes the connection to the given patterns.

func (PubSubConn) PUnsubscribe 

func (c PubSubConn) PUnsubscribe(channel ...interface{}) error

PUnsubscribe unsubscribes the connection from the given patterns, or from all of them if none is given.

func (PubSubConn) Ping 

func (c PubSubConn) Ping(data string) error

Ping sends a PING to the server with the specified data.

The connection must be subscribed to at least one channel or pattern when calling this method.

func (PubSubConn) Receive 

func (c PubSubConn) Receive() interface{}

Receive returns a pushed message as a Subscription, Message, Pong or error. The return value is intended to be used directly in a type switch as illustrated in the PubSubConn example.

func (PubSubConn) ReceiveContext added in v1.8.9 

func (c PubSubConn) ReceiveContext(ctx context.Context) interface{}

ReceiveContext is like Receive, but it allows termination of the receive via a Context. If the call returns due to closure of the context's Done channel the underlying Conn will have been closed.

func (PubSubConn) ReceiveWithTimeout 

func (c PubSubConn) ReceiveWithTimeout(timeout time.Duration) interface{}

ReceiveWithTimeout is like Receive, but it allows the application to override the connection's default timeout.

func (PubSubConn) Subscribe 

func (c PubSubConn) Subscribe(channel ...interface{}) error

Subscribe subscribes the connection to the specified channels.

func (PubSubConn) Unsubscribe 

func (c PubSubConn) Unsubscribe(channel ...interface{}) error

Unsubscribe unsubscribes the connection from the given channels, or from all of them if none is given.

type Scanner 

type Scanner interface {
	// RedisScan assigns a value from a Redis value. The argument src is one of
	// the reply types listed in the section `Executing Commands`.
	//
	// An error should be returned if the value cannot be stored without
	// loss of information.
	RedisScan(src interface{}) error
}

Scanner is implemented by an object which wants to control its value is interpreted when read from Redis.

type Script 

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

Script encapsulates the source, hash and key count for a Lua script. See http://redis.io/commands/eval for information on scripts in Redis.

Example 
package main

import (
	"github.com/gomodule/redigo/redis"
)

var (
	c     redis.Conn
	reply interface{}
	err   error
)

func main() {
	// Initialize a package-level variable with a script.
	var getScript = redis.NewScript(1, `return redis.call('get', KEYS[1])`)

	// In a function, use the script Do method to evaluate the script. The Do
	// method optimistically uses the EVALSHA command. If the script is not
	// loaded, then the Do method falls back to the EVAL command.
	reply, err = getScript.Do(c, "foo")
}

Output:

func NewScript 

func NewScript(keyCount int, src string) *Script

NewScript returns a new script object. If keyCount is greater than or equal to zero, then the count is automatically inserted in the EVAL command argument list. If keyCount is less than zero, then the application supplies the count as the first value in the keysAndArgs argument to the Do, Send and SendHash methods.

func (*Script) Do 

func (s *Script) Do(c Conn, keysAndArgs ...interface{}) (interface{}, error)

Do evaluates the script. Under the covers, Do optimistically evaluates the script using the EVALSHA command. If the command fails because the script is not loaded, then Do evaluates the script using the EVAL command (thus causing the script to load).

func (*Script) DoContext added in v1.8.6 

func (s *Script) DoContext(ctx context.Context, c Conn, keysAndArgs ...interface{}) (interface{}, error)

func (*Script) Hash 

func (s *Script) Hash() string

Hash returns the script hash.

func (*Script) Load 

func (s *Script) Load(c Conn) error

Load loads the script without evaluating it.

func (*Script) Send 

func (s *Script) Send(c Conn, keysAndArgs ...interface{}) error

Send evaluates the script without waiting for the reply.

func (*Script) SendHash 

func (s *Script) SendHash(c Conn, keysAndArgs ...interface{}) error

SendHash evaluates the script without waiting for the reply. The script is evaluated with the EVALSHA command. The application must ensure that the script is loaded by a previous call to Send, Do or Load methods.

type SlowLog added in v1.7.2 

type SlowLog struct {
	// ID is a unique progressive identifier for every slow log entry.
	ID int64

	// Time is the unix timestamp at which the logged command was processed.
	Time time.Time

	// ExecutationTime is the amount of time needed for the command execution.
	ExecutionTime time.Duration

	// Args is the command name and arguments
	Args []string

	// ClientAddr is the client IP address (4.0 only).
	ClientAddr string

	// ClientName is the name set via the CLIENT SETNAME command (4.0 only).
	ClientName string
}

SlowLog represents a redis SlowLog

func SlowLogs added in v1.7.2 

func SlowLogs(result interface{}, err error) ([]SlowLog, error)

SlowLogs is a helper that parse the SLOWLOG GET command output and return the array of SlowLog

type Subscription 

type Subscription struct {
	// Kind is "subscribe", "unsubscribe", "psubscribe" or "punsubscribe"
	Kind string

	// The channel that was changed.
	Channel string

	// The current number of subscriptions for connection.
	Count int
}

Subscription represents a subscribe or unsubscribe notification.

Source Files

View all Source files

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.