API Reference

This page provides a high-level overview of the key public types, functions, and methods in the Redigo redis package.

Connections

redis.Conn

The primary interface for interacting with Redis.

  • Do(commandName string, args ...interface{}) (reply interface{}, err error): Executes a command and returns its reply.
  • Send(commandName string, args ...interface{}) error: Writes a command to the output buffer for pipelining.
  • Flush() error: Flushes the output buffer to the server.
  • Receive() (reply interface{}, err error): Reads a single reply from the server.
  • Close() error: Closes the connection.
  • Err() error: Returns a non-nil error if the connection has encountered a fatal error.

Connection Functions

  • Dial(network, address string, options ...DialOption) (Conn, error): Establishes a new connection.
  • DialURL(rawurl string, options ...DialOption) (Conn, error): Establishes a new connection using a Redis URI.

DialOption

A type used to configure connections. Common options include:

  • DialConnectTimeout(d time.Duration)
  • DialReadTimeout(d time.Duration)
  • DialWriteTimeout(d time.Duration)
  • DialDatabase(db int)
  • DialPassword(password string)
  • DialUsername(username string)
  • DialUseTLS(useTLS bool)

Connection Pooling

redis.Pool

A thread-safe pool for managing Redis connections.

Key Fields:

  • Dial func() (Conn, error): A function to create new connections.
  • MaxIdle int: Maximum number of idle connections.
  • MaxActive int: Maximum number of active connections.
  • IdleTimeout time.Duration: Timeout for closing idle connections.
  • Wait bool: Whether to wait for a connection when MaxActive is reached.
  • TestOnBorrow func(c Conn, t time.Time) error: A function to check connection health.

Key Methods:

  • Get() Conn: Retrieves a connection from the pool.
  • GetContext(ctx context.Context) (Conn, error): Retrieves a connection, respecting the context.
  • Close() error: Closes the pool and all its connections.
  • Stats() PoolStats: Returns statistics about the pool.

Publish & Subscribe

redis.PubSubConn

A wrapper around redis.Conn for Pub/Sub operations.

  • Subscribe(channel ...interface{}) error
  • PSubscribe(pattern ...interface{}) error
  • Unsubscribe(channel ...interface{}) error
  • PUnsubscribe(pattern ...interface{}) error
  • Receive() interface{}: Receives a notification, which can be cast to redis.Message, redis.Subscription, redis.Pong, or error.
  • Close() error

Pub/Sub Types

  • redis.Message: {Channel string, Pattern string, Data []byte}
  • redis.Subscription: {Kind string, Channel string, Count int}

Lua Scripting

redis.Script

A helper type for managing and executing Lua scripts.

  • NewScript(keyCount int, src string) *Script: Creates a new script object.
  • Do(c Conn, keysAndArgs ...interface{}) (interface{}, error): Executes the script, automatically handling EVALSHA vs. EVAL.
  • Load(c Conn) error: Pre-loads the script into the server's cache.
  • Send(c Conn, keysAndArgs ...interface{}) error: Sends an EVAL command for pipelining.
  • SendHash(c Conn, keysAndArgs ...interface{}) error: Sends an EVALSHA command for pipelining.

Reply Helpers

These functions convert interface{} replies from Do() or Receive() to specific Go types.

Scalar Types:

  • Bool(reply, err)
  • Bytes(reply, err)
  • Float64(reply, err)
  • Int(reply, err)
  • Int64(reply, err)
  • String(reply, err)
  • Uint64(reply, err)

Slice Types:

  • Values(reply, err) -> []interface{}
  • ByteSlices(reply, err) -> [][]byte
  • Strings(reply, err) -> []string
  • Ints(reply, err) -> []int

Map Types:

  • StringMap(reply, err) -> map[string]string
  • IntMap(reply, err) -> map[string]int

Scanning:

  • Scan(src []interface{}, dest ...interface{}): Scans an array reply into variables.
  • ScanStruct(src []interface{}, dest interface{}): Scans a key-value array reply into a struct.
  • ScanSlice(src []interface{}, dest interface{}): Scans a flat array reply into a slice of structs.