Overview ▹

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 method.

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)

▾ Example (Zpop)

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

Code:

package redis_test

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")
        }
    }()

    // 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
        }

        c.Send("MULTI")
        c.Send("ZREM", key, members[0])
        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 Example_zpop() {
    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"} {
        c.Send("ZADD", "zset", i, member)
    }
    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
}

Package redis

Overview ▹

Overview ▾

Connections

Executing Commands

Pipelining

Concurrency

Publish and Subscribe

Reply Helpers

Errors

Index ▹

Index ▾

Examples

Package files

Variables

func Bool ¶

func ByteSlices ¶

func Bytes ¶

func DoWithTimeout ¶

func Float64 ¶

func Float64s ¶

func Int ¶

func Int64 ¶

func Int64Map ¶

func Int64s ¶

func IntMap ¶

func Ints ¶

func MultiBulk ¶

func Positions ¶

func ReceiveWithTimeout ¶

func Scan ¶

func ScanSlice ¶

func ScanStruct ¶

func String ¶

func StringMap ¶

func Strings ¶

func Uint64 ¶

func Values ¶

type Args ¶

func (Args) Add ¶

func (Args) AddFlat ¶

type Argument ¶

type Conn ¶

func Dial ¶

func DialTimeout ¶

func DialURL ¶

func NewConn ¶

func NewLoggingConn ¶

type ConnWithTimeout ¶

type DialOption ¶

func DialConnectTimeout ¶

func DialDatabase ¶

func DialKeepAlive ¶

func DialNetDial ¶

func DialPassword ¶

func DialReadTimeout ¶

func DialTLSConfig ¶

func DialTLSSkipVerify ¶

func DialUseTLS ¶

func DialWriteTimeout ¶

type Error ¶

func (Error) Error ¶

type Message ¶

type Pong ¶

type Pool ¶

func NewPool ¶

func (*Pool) ActiveCount ¶

func (*Pool) Close ¶

func (*Pool) Get ¶

func (*Pool) GetContext ¶

func (*Pool) IdleCount ¶

func (*Pool) Stats ¶

type PoolStats ¶

type PubSubConn ¶

func (PubSubConn) Close ¶

func (PubSubConn) PSubscribe ¶

func (PubSubConn) PUnsubscribe ¶

func (PubSubConn) Ping ¶

func (PubSubConn) Receive ¶

func (PubSubConn) ReceiveWithTimeout ¶