1 // Copyright 2012 Gary Burd 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"): you may 4 // not use this file except in compliance with the License. You may obtain 5 // a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations 13 // under the License. 14 15 // Package redis is a client for the Redis database. 16 // 17 // The Redigo FAQ (https://github.com/gomodule/redigo/wiki/FAQ) contains more 18 // documentation about this package. 19 // 20 // Connections 21 // 22 // The Conn interface is the primary interface for working with Redis. 23 // Applications create connections by calling the Dial, DialWithTimeout or 24 // NewConn functions. In the future, functions will be added for creating 25 // sharded and other types of connections. 26 // 27 // The application must call the connection Close method when the application 28 // is done with the connection. 29 // 30 // Executing Commands 31 // 32 // The Conn interface has a generic method for executing Redis commands: 33 // 34 // Do(commandName string, args ...interface{}) (reply interface{}, err error) 35 // 36 // The Redis command reference (http://redis.io/commands) lists the available 37 // commands. An example of using the Redis APPEND command is: 38 // 39 // n, err := conn.Do("APPEND", "key", "value") 40 // 41 // The Do method converts command arguments to bulk strings for transmission 42 // to the server as follows: 43 // 44 // Go Type Conversion 45 // []byte Sent as is 46 // string Sent as is 47 // int, int64 strconv.FormatInt(v) 48 // float64 strconv.FormatFloat(v, 'g', -1, 64) 49 // bool true -> "1", false -> "0" 50 // nil "" 51 // all other types fmt.Fprint(w, v) 52 // 53 // Redis command reply types are represented using the following Go types: 54 // 55 // Redis type Go type 56 // error redis.Error 57 // integer int64 58 // simple string string 59 // bulk string []byte or nil if value not present. 60 // array []interface{} or nil if value not present. 61 // 62 // Use type assertions or the reply helper functions to convert from 63 // interface{} to the specific Go type for the command result. 64 // 65 // Pipelining 66 // 67 // Connections support pipelining using the Send, Flush and Receive methods. 68 // 69 // Send(commandName string, args ...interface{}) error 70 // Flush() error 71 // Receive() (reply interface{}, err error) 72 // 73 // Send writes the command to the connection's output buffer. Flush flushes the 74 // connection's output buffer to the server. Receive reads a single reply from 75 // the server. The following example shows a simple pipeline. 76 // 77 // c.Send("SET", "foo", "bar") 78 // c.Send("GET", "foo") 79 // c.Flush() 80 // c.Receive() // reply from SET 81 // v, err = c.Receive() // reply from GET 82 // 83 // The Do method combines the functionality of the Send, Flush and Receive 84 // methods. The Do method starts by writing the command and flushing the output 85 // buffer. Next, the Do method receives all pending replies including the reply 86 // for the command just sent by Do. If any of the received replies is an error, 87 // then Do returns the error. If there are no errors, then Do returns the last 88 // reply. If the command argument to the Do method is "", then the Do method 89 // will flush the output buffer and receive pending replies without sending a 90 // command. 91 // 92 // Use the Send and Do methods to implement pipelined transactions. 93 // 94 // c.Send("MULTI") 95 // c.Send("INCR", "foo") 96 // c.Send("INCR", "bar") 97 // r, err := c.Do("EXEC") 98 // fmt.Println(r) // prints [1, 1] 99 // 100 // Concurrency 101 // 102 // Connections support one concurrent caller to the Receive method and one 103 // concurrent caller to the Send and Flush methods. No other concurrency is 104 // supported including concurrent calls to the Do method. 105 // 106 // For full concurrent access to Redis, use the thread-safe Pool to get, use 107 // and release a connection from within a goroutine. Connections returned from 108 // a Pool have the concurrency restrictions described in the previous 109 // paragraph. 110 // 111 // Publish and Subscribe 112 // 113 // Use the Send, Flush and Receive methods to implement Pub/Sub subscribers. 114 // 115 // c.Send("SUBSCRIBE", "example") 116 // c.Flush() 117 // for { 118 // reply, err := c.Receive() 119 // if err != nil { 120 // return err 121 // } 122 // // process pushed message 123 // } 124 // 125 // The PubSubConn type wraps a Conn with convenience methods for implementing 126 // subscribers. The Subscribe, PSubscribe, Unsubscribe and PUnsubscribe methods 127 // send and flush a subscription management command. The receive method 128 // converts a pushed message to convenient types for use in a type switch. 129 // 130 // psc := redis.PubSubConn{Conn: c} 131 // psc.Subscribe("example") 132 // for { 133 // switch v := psc.Receive().(type) { 134 // case redis.Message: 135 // fmt.Printf("%s: message: %s\n", v.Channel, v.Data) 136 // case redis.Subscription: 137 // fmt.Printf("%s: %s %d\n", v.Channel, v.Kind, v.Count) 138 // case error: 139 // return v 140 // } 141 // } 142 // 143 // Reply Helpers 144 // 145 // The Bool, Int, Bytes, String, Strings and Values functions convert a reply 146 // to a value of a specific type. To allow convenient wrapping of calls to the 147 // connection Do and Receive methods, the functions take a second argument of 148 // type error. If the error is non-nil, then the helper function returns the 149 // error. If the error is nil, the function converts the reply to the specified 150 // type: 151 // 152 // exists, err := redis.Bool(c.Do("EXISTS", "foo")) 153 // if err != nil { 154 // // handle error return from c.Do or type conversion error. 155 // } 156 // 157 // The Scan function converts elements of a array reply to Go types: 158 // 159 // var value1 int 160 // var value2 string 161 // reply, err := redis.Values(c.Do("MGET", "key1", "key2")) 162 // if err != nil { 163 // // handle error 164 // } 165 // if _, err := redis.Scan(reply, &value1, &value2); err != nil { 166 // // handle error 167 // } 168 // 169 // Errors 170 // 171 // Connection methods return error replies from the server as type redis.Error. 172 // 173 // Call the connection Err() method to determine if the connection encountered 174 // non-recoverable error such as a network error or protocol parsing error. If 175 // Err() returns a non-nil value, then the connection is not usable and should 176 // be closed. 177 package redis // import "github.com/gomodule/redigo/redis" 178