radix.v2: github.com/mediocregopher/radix.v2/redis Index | Files

package redis

import "github.com/mediocregopher/radix.v2/redis"

Package redis is a simple client for connecting and interacting with a single redis instance.

THE FUNCTIONALITY PROVIDED IN THIS PACKAGE IS NOT THREAD-SAFE. To use a single redis instance amongst multiple go-routines, check out the pool subpackage (http://godoc.org/github.com/mediocregopher/radix.v2/pool)

To import inside your package do:

import "github.com/mediocregopher/radix.v2/redis"


Use either Dial or DialTimeout:

client, err := redis.Dial("tcp", "localhost:6379")
if err != nil {
	// handle err

Make sure to call Close on the client if you want to clean it up before the end of the program.

Cmd and Resp

The Cmd method returns a Resp, which has methods for converting to various types. Each of these methods returns an error which can either be a connection error (e.g. timeout), an application error (e.g. key is wrong type), or a conversion error (e.g. cannot convert to integer). You can also directly check the error using the Err field:

foo, err := client.Cmd("GET", "foo").Str()
if err != nil {
	// handle err

// Checking Err field directly

err = client.Cmd("SET", "foo", "bar", "EX", 3600).Err
if err != nil {
	// handle err

Array Replies

The elements to Array replies can be accessed as strings using List or ListBytes, or you can use the Array method for more low level access:

r := client.Cmd("MGET", "foo", "bar", "baz")
if r.Err != nil {
	// handle error

// This:
l, _ := r.List()
for _, elemStr := range l {

// is equivalent to this:
elems, err := r.Array()
for i := range elems {
	elemStr, _ := elems[i].Str()


Pipelining is when the client sends a bunch of commands to the server at once, and only once all the commands have been sent does it start reading the replies off the socket. This is supported using the PipeAppend and PipeResp methods. PipeAppend will simply append the command to a buffer without sending it, the first time PipeResp is called it will send all the commands in the buffer and return the Resp for the first command that was sent. Subsequent calls to PipeResp return Resps for subsequent commands:

client.PipeAppend("GET", "foo")
client.PipeAppend("SET", "bar", "foo")
client.PipeAppend("DEL", "baz")

// Read GET foo reply
foo, err := client.PipeResp().Str()
if err != nil {
	// handle err

// Read SET bar foo reply
if err := client.PipeResp().Err; err != nil {
	// handle err

// Read DEL baz reply
if err := client.PipeResp().Err; err != nil {
	// handle err


Radix will automatically flatten passed in maps and slices into the argument list. For example, the following are all equivalent:

client.Cmd("HMSET", "myhash", "key1", "val1", "key2", "val2")
client.Cmd("HMSET", "myhash", []string{"key1", "val1", "key2", "val2"})
client.Cmd("HMSET", "myhash", map[string]string{
	"key1": "val1",
	"key2": "val2",
client.Cmd("HMSET", "myhash", [][]string{
	[]string{"key1", "val1"},
	[]string{"key2", "val2"},

Radix is not picky about the types inside or outside the maps/slices, if they don't match a subset of primitive types it will fall back to reflection to figure out what they are and encode them.


Package Files

client.go doc.go resp.go


var ErrPipelineEmpty = errors.New("pipeline queue empty")

ErrPipelineEmpty is returned from PipeResp() to indicate that all commands which were put into the pipeline have had their responses read

var (

    // ErrRespNil is returned from methods on Resp like Str, Int, etc... when
    // called on a Resp which is a nil response
    ErrRespNil = errors.New("response is nil")

Parse errors

func IsTimeout Uses

func IsTimeout(r *Resp) bool

IsTimeout is a helper function for determining if an IOErr Resp was caused by a network timeout

func KeyFromArgs Uses

func KeyFromArgs(args ...interface{}) (string, error)

KeyFromArgs is a helper function which other library packages which wrap this one might find useful. It takes in a set of arguments which might be passed into Cmd and returns the first key for the command. Since radix supports complicated arguments (like slices, slices of slices, maps, etc...) this is not always as straightforward as it might seem, so this helper function is provided.

An error is returned if no key can be determined

type Client Uses

type Client struct {

    // The network/address of the redis instance this client is connected to.
    // These will be whatever strings were passed into the Dial function when
    // creating this connection
    Network, Addr string

    // These define the max time to spend blocking on read/write connections
    // during commands. These should not be set to zero if they were ever not
    // zero. These may be set after the Client is initialized, but not while any
    // methods are being called. DialTimeout will set both of these to its
    // passed in value.
    ReadTimeout, WriteTimeout time.Duration

    // The most recent network error which occurred when either reading
    // or writing. A critical network error is basically any non-application
    // level error, e.g. a timeout, disconnect, etc... Close is automatically
    // called on the client when it encounters a critical network error
    // NOTE: The ReadResp method does *not* consider a timeout to be a critical
    // network error, and will not set this field in the event of one. Other
    // methods which deal with a command-then-response (e.g. Cmd, PipeResp) do
    // set this and close the connection in the event of a timeout
    LastCritical error
    // contains filtered or unexported fields

Client describes a Redis client.

func Dial Uses

func Dial(network, addr string) (*Client, error)

Dial connects to the given Redis server.

func DialTimeout Uses

func DialTimeout(network, addr string, timeout time.Duration) (*Client, error)

DialTimeout connects to the given Redis server with the given timeout, which will be used as the read/write timeout when communicating with redis

func (*Client) Close Uses

func (c *Client) Close() error

Close closes the connection.

func (*Client) Cmd Uses

func (c *Client) Cmd(cmd string, args ...interface{}) *Resp

Cmd calls the given Redis command.

func (*Client) PipeAppend Uses

func (c *Client) PipeAppend(cmd string, args ...interface{})

PipeAppend adds the given call to the pipeline queue. Use PipeResp() to read the response.

func (*Client) PipeClear Uses

func (c *Client) PipeClear() (int, int)

PipeClear clears the contents of the current pipeline queue, both commands queued by PipeAppend which have yet to be sent and responses which have yet to be retrieved through PipeResp. The first returned int will be the number of pending commands dropped, the second will be the number of pending responses dropped

func (*Client) PipeResp Uses

func (c *Client) PipeResp() *Resp

PipeResp returns the reply for the next request in the pipeline queue. Err with ErrPipelineEmpty is returned if the pipeline queue is empty.

func (*Client) ReadResp Uses

func (c *Client) ReadResp() *Resp

ReadResp will read a Resp off of the connection without sending anything first (useful after you've sent a SUSBSCRIBE command). This will block until a reply is received or the timeout is reached (returning the IOErr). You can use IsTimeout to check if the Resp is due to a Timeout

Note: this is a more low-level function, you really shouldn't have to actually use it unless you're writing your own pub/sub code

type Resp Uses

type Resp struct {

    // Err indicates that this Resp signals some kind of error, either on the
    // connection level or the application level. Use IsType if you need to
    // determine which, otherwise you can simply check if this is nil
    Err error
    // contains filtered or unexported fields

Resp represents a single response or message being sent to/from a redis server. Each Resp has a type (see RespType and IsType) and a value. Values can be retrieved using any of the casting methods on this type (e.g. Str)

func NewResp Uses

func NewResp(v interface{}) *Resp

NewResp takes the given value and interprets it into a resp encoded byte stream

func NewRespFlattenedStrings Uses

func NewRespFlattenedStrings(v interface{}) *Resp

NewRespFlattenedStrings is like NewResp except it looks through the given value and converts any types (except slices/maps) into strings, and flatten any embedded slices/maps into a single slice. This is useful because commands to a redis server must be given as an array of bulk strings. If the argument isn't already in a slice/map it will be wrapped so that it is written as a Array of size one

func NewRespIOErr Uses

func NewRespIOErr(err error) *Resp

NewRespIOErr takes an error and creates an IOErr response. Use NewResp instead to create an AppErr response.

func NewRespSimple Uses

func NewRespSimple(s string) *Resp

NewRespSimple is like NewResp except it encodes its string as a resp SimpleStr type, whereas NewResp will encode all strings as BulkStr

func (*Resp) Array Uses

func (r *Resp) Array() ([]*Resp, error)

Array returns the Resp slice encompassed by this Resp. Only valid for a Resp of type Array. If r.Err != nil that will be returned

func (*Resp) Bytes Uses

func (r *Resp) Bytes() ([]byte, error)

Bytes returns a byte slice representing the value of the Resp. Only valid for a Resp of type Str. If r.Err != nil that will be returned.

func (*Resp) Float64 Uses

func (r *Resp) Float64() (float64, error)

Float64 returns a float64 representing the value of the Resp. Only valud for a Resp of type Str which represents an actual float. If r.Err != nil that will be returned

func (*Resp) Int Uses

func (r *Resp) Int() (int, error)

Int returns an int representing the value of the Resp. For a Resp of type Int the integer value will be returned directly. For a Resp of type Str the string will attempt to be parsed as a base-10 integer, returning the parsing error if any. If r.Err != nil that will be returned

func (*Resp) Int64 Uses

func (r *Resp) Int64() (int64, error)

Int64 is like Int, but returns int64 instead of Int

func (*Resp) IsType Uses

func (r *Resp) IsType(t RespType) bool

IsType returns whether or or not the reply is of a given type

isStr := r.IsType(redis.Str)

Multiple types can be checked at the same time by or'ing the desired types

isStrOrInt := r.IsType(redis.Str | redis.Int)

func (*Resp) List Uses

func (r *Resp) List() ([]string, error)

List is a wrapper around Array which returns the result as a list of strings, calling Str() on each Resp which Array returns. Any errors encountered are immediately returned. Any Nil replies are interpreted as empty strings

func (*Resp) ListBytes Uses

func (r *Resp) ListBytes() ([][]byte, error)

ListBytes is a wrapper around Array which returns the result as a list of byte slices, calling Bytes() on each Resp which Array returns. Any errors encountered are immediately returned. Any Nil replies are interpreted as nil

func (*Resp) Map Uses

func (r *Resp) Map() (map[string]string, error)

Map is a wrapper around Array which returns the result as a map of strings, calling Str() on alternating key/values for the map. All value fields of type Nil will be treated as empty strings, keys must all be of type Str

func (*Resp) Str Uses

func (r *Resp) Str() (string, error)

Str is a wrapper around Bytes which returns the result as a string instead of a byte slice

func (*Resp) String Uses

func (r *Resp) String() string

String returns a string representation of the Resp. This method is for debugging, use Str() for reading a Str reply

func (*Resp) WriteTo Uses

func (r *Resp) WriteTo(w io.Writer) (int64, error)

WriteTo writes the resp encoded form of the Resp to the given writer, implementing the WriterTo interface

type RespReader Uses

type RespReader struct {
    // contains filtered or unexported fields

RespReader is a wrapper around an io.Reader which will read Resp messages off of the io.Reader

func NewRespReader Uses

func NewRespReader(r io.Reader) *RespReader

NewRespReader creates and returns a new RespReader which will read from the given io.Reader. Once passed in the io.Reader shouldn't be read from by any other processes

func (*RespReader) Read Uses

func (rr *RespReader) Read() *Resp

ReadResp attempts to read a message object from the given io.Reader, parse it, and return a Resp representing it

type RespType Uses

type RespType int

RespType is a field on every Resp which indicates the type of the data it contains

const (
    SimpleStr RespType = 1 << iota
    IOErr  // An error which prevented reading/writing, e.g. connection close
    AppErr // An error returned by redis, e.g. WRONGTYPE

    // Str combines both SimpleStr and BulkStr, which are considered strings to
    // the Str() method.  This is what you want to give to IsType when
    // determining if a response is a string
    Str = SimpleStr | BulkStr

    // Err combines both IOErr and AppErr, which both indicate that the Err
    // field on their Resp is filled. To determine if a Resp is an error you'll
    // most often want to simply check if the Err field on it is nil
    Err = IOErr | AppErr

Different RespTypes. You can check if a message is of one or more types using the IsType method on Resp

Package redis imports 10 packages (graph) and is imported by 113 packages. Updated 2017-08-21. Refresh now. Tools for package owners.