redis/README.md

Readme
======

Redis client for Golang.

Supports:

- Redis 2.6 commands except QUIT, MONITOR, SLOWLOG and SYNC.
- Pub/sub.
- Transactions.
- Pipelining.
- Connection pool.
- TLS connections.
- Thread safety.

Installation
------------

Install:

    go get github.com/vmihailenco/redis

Getting Client instance
-----------------------

Example 1:

    import "github.com/vmihailenco/redis"


    address := "localhost:6379"
    password := "secret"
    db := 0
    redisClient := redis.NewTCPClient(address, password, db)

Example 2:

    import "github.com/vmihailenco/redis"


    openConn := func() (net.Conn, error) {
        fmt.Println("Connecting...")
        return net.Dial("tcp", ":6379")
    }

    closeConn := func(conn net.Conn) error {
        fmt.Println("Disconnecting...")
        return nil
    }

    initConn := func(client *redis.Client) error {
         auth := client.Auth("key")
         if err := auth.Err(); err != nil {
             return err
         }

         ping := client.Ping()
         if err := ping.Err(); err != nil {
             return err
         }

         return nil
    }

    redisClient := redis.NewClient(openConn, closeConn, initConn)

Both `closeConn` and `initConn` functions can be `nil`.

Running commands
----------------

    set := redisClient.Set("key", "hello")
    if err := set.Err(); err != nil {
        panic(err)
    }
    ok := set.Val()

    get := redisClient.Get("key")
    if err := get.Err(); err != nil && err != redis.Nil {
        panic(err)
    }
    val := get.Val()

Pipelining
----------

Client has ability to run commands in batches:

    reqs, err := redisClient.Pipelined(func(c *redis.PipelineClient) {
        c.Set("key1", "hello1") // queue command SET
        c.Set("key2", "hello2") // queue command SET
    })
    if err != nil {
        panic(err)
    }
    for _, req := range reqs {
        // ...
    }

Or:

    pipeline, err := redisClient.PipelineClient()
    if err != nil {
        panic(err)
    }
    defer pipeline.Close()

    setReq := pipeline.Set("key1", "hello1") // queue command SET
    getReq := pipeline.Get("key2") // queue command GET

    reqs, err := pipeline.RunQueued() // run queued commands
    if err != nil {
        panic(err)
    }
    for _, req := range reqs {
        // ...
    }

    if err := setReq.Err(); err != nil {
        panic(err
    }

    if err := getReq.Err(); err != nil && err != redis.Nil {
        panic(err)
    }

Multi/Exec
----------

Example:

    func transaction(multi *redis.MultiClient) ([]redis.Req, error) {
        get := multiClient.Get("key")
        if err := get.Err(); err != nil {
            panic(err)
        }

        reqs, err = multiClient.Exec(func() {
            multi.Set("key", get.Val() + "1")
        })
        if err == redis.Nil {
            return transaction()
        }

        return reqs, err
    }

    multiClient, err := redisClient.MultiClient()
    if err != nil {
        panic(err)
    }
    defer multiClient.Close()

    watch := multiClient.Watch("key")
    if err := watch.Err(); err != nil {
        panic(err)
    }

    reqs, err := transaction(multiClient)
    if err != nil {
        panic(err)
    }
    for _, req := range reqs {
        // ...
    }

Pub/sub
-------

Publish:

    pub := redisClient.Publish("mychannel", "hello")
    if err := pub.Err(); err != nil {
        panic(err)
    }

Subscribe:

    pubsub, err := redisClient.PubSubClient()
    if err != nil {
        panic(err)
    }
    defer pubsub.Close()

    ch, err := pubsub.Subscribe("mychannel")
    if err != nil {
        panic(err)
    }

    go func() {
        for msg := range ch {
            if msg.Err != nil {
                panic(err)
            }
            message := msg.Message
        }
    }

Thread safety
-------------

Commands are thread safe. Following code is correct:

    for i := 0; i < 1000; i++ {
        go func() {
            redisClient.Incr("key")
        }()
    }

Custom commands
---------------

Example:

    func Get(client *redis.Client, key string) *redis.BulkReq {
        req := redis.NewBulkReq("GET", key)
        client.Process(req)
        return req
    }

    get := Get(redisClient, "key")
    if err := get.Err(); err != nil && err != redis.Nil {
        panic(err)
    }

Connection pool
---------------

Client uses connection pool with default capacity of 10 connections. To change pool capacity:

    redisClient.ConnPool.(*redis.MultiConnPool).MaxCap = 1

Look and feel
-------------

Some corner cases:

    SORT list LIMIT 0 2 ASC
    client.Sort("list", redis.Sort{Offset: 0, Count: 2, Order: "ASC"})

    ZRANGEBYSCORE zset -inf +inf WITHSCORES LIMIT 0 2
    client.ZRangeByScoreWithScores("zset", "-inf", "+inf", 0, 2)

    ZINTERSTORE out 2 zset1 zset2 WEIGHTS 2 3 AGGREGATE SUM
    client.ZInterStore("out", redis.ZStore{Weights: []int64{2, 3}}, "zset1", "zset2")

    EVAL "return {KEYS[1],ARGV[1]}" 1 "key" "hello"
    client.Eval("return {KEYS[1],ARGV[1]}", []string{"key"}, []string{"hello"})

Contributing
------------

Configure Redis to allow maximum 10 clients:

    maxclients 10

Run tests:

    go test -gocheck.v

Run benchmarks:

    go test -gocheck.b