rediscala
A Redis client for Scala (2.11+) and (AKKA 2.5+) with non-blocking and asynchronous I/O operations.
-
Reactive : Redis requests/replies are wrapped in Futures.
-
Typesafe : Redis types are mapped to Scala types.
-
Fast : Rediscala uses redis pipelining. Blocking redis commands are moved into their own connection. A worker actor handles I/O operations (I/O bounds), another handles decoding of Redis replies (CPU bounds).
State of the project
This is an unofficial fork from etaty/rediscala maintained by @herzrasen, @kardapoltsev and @Ma27 which was started as the original maintainer was too unresponsive to keep the project alive as discussed in etaty/rediscala#191.
Note: please keep in mind that we mainly want to keep the project alive, but lack time to do active development. If you're interested in helping out, just open an issue.
Set up your project dependencies
If you use SBT, you just have to edit build.sbt
and add the following:
From version 1.8.0:
- use Akka 2.5 (Java 1.8)
- released for Scala 2.11 & 2.12
libraryDependencies += "com.github.Ma27" %% "rediscala" % "1.8.4"
Connect to the database
import redis.RedisClient
import scala.concurrent.Await
import scala.concurrent.duration._
import scala.concurrent.ExecutionContext.Implicits.global
object Main extends App {
implicit val akkaSystem = akka.actor.ActorSystem()
val redis = RedisClient()
val futurePong = redis.ping()
println("Ping sent!")
futurePong.map(pong => {
println(s"Redis replied with a $pong")
})
Await.result(futurePong, 5 seconds)
akkaSystem.terminate()
}
Basic Example
https://github.com/etaty/rediscala-demo
You can fork with : git clone git@github.com:etaty/rediscala-demo.git
then run it, with sbt run
Redis Commands
All commands are supported :
- Keys (scaladoc)
- Strings (scaladoc)
- Hashes (scaladoc)
- Lists
- Sets (scaladoc)
- Sorted Sets (scaladoc)
- Pub/Sub (scaladoc)
- Transactions (scaladoc)
- Connection (scaladoc)
- Scripting (scaladoc)
- Server (scaladoc)
- HyperLogLog (scaladoc)
Blocking commands
RedisBlockingClient is the instance allowing access to blocking commands :
- blpop
- brpop
- brpopplush
redisBlocking.blpop(Seq("workList", "otherKeyWithWork"), 5 seconds).map(result => {
result.map({
case (key, work) => println(s"list $key has work : ${work.utf8String}")
})
})
Full example: ExampleRediscalaBlocking
You can fork with: git clone git@github.com:etaty/rediscala-demo.git
then run it, with sbt run
Transactions
The idea behind transactions in Rediscala is to start a transaction outside of a redis connection.
We use the TransactionBuilder to store call to redis commands (and for each command we give back a future).
When exec
is called, TransactionBuilder
will build and send all the commands together to the server. Then the futures will be completed.
By doing that we can use a normal connection with pipelining, and avoiding to trap a command from outside, in the transaction...
val redisTransaction = redis.transaction() // new TransactionBuilder
redisTransaction.watch("key")
val set = redisTransaction.set("key", "abcValue")
val decr = redisTransaction.decr("key")
val get = redisTransaction.get("key")
redisTransaction.exec()
Full example: ExampleTransaction
You can fork with : git clone git@github.com:etaty/rediscala-demo.git
then run it, with sbt run
TransactionsSpec will reveal even more gems of the API.
Pub/Sub
You can use a case class with callbacks RedisPubSub or extend the actor RedisSubscriberActor as shown in the example below
object ExamplePubSub extends App {
implicit val akkaSystem = akka.actor.ActorSystem()
val redis = RedisClient()
// publish after 2 seconds every 2 or 5 seconds
akkaSystem.scheduler.schedule(2 seconds, 2 seconds)(redis.publish("time", System.currentTimeMillis()))
akkaSystem.scheduler.schedule(2 seconds, 5 seconds)(redis.publish("pattern.match", "pattern value"))
// shutdown Akka in 20 seconds
akkaSystem.scheduler.scheduleOnce(20 seconds)(akkaSystem.terminate())
val channels = Seq("time")
val patterns = Seq("pattern.*")
// create SubscribeActor instance
akkaSystem.actorOf(Props(classOf[SubscribeActor], channels, patterns).withDispatcher("rediscala.rediscala-client-worker-dispatcher"))
}
class SubscribeActor(channels: Seq[String] = Nil, patterns: Seq[String] = Nil) extends RedisSubscriberActor(channels, patterns) {
override val address: InetSocketAddress = new InetSocketAddress("localhost", 6379)
def onMessage(message: Message) {
println(s"message received: $message")
}
def onPMessage(pmessage: PMessage) {
println(s"pattern message received: $pmessage")
}
}
Full example: ExamplePubSub
You can fork with : git clone git@github.com:etaty/rediscala-demo.git
then run it, with sbt run
RedisPubSubSpec will reveal even more gems of the API.
Scripting
RedisScript
is a helper, you can put your LUA script inside and it will compute the hash.
You can use it with evalshaOrEval
which run your script even if it wasn't already loaded.
val redis = RedisClient()
val redisScript = RedisScript("return 'rediscala'")
val r = redis.evalshaOrEval(redisScript).map({
case b: Bulk => println(b.toString())
})
Await.result(r, 5 seconds)
Full example: ExampleScripting
Redis Sentinel
SentinelClient connect to a redis sentinel server.
SentinelMonitoredRedisClient connect to a sentinel server to find the master addresse then start a connection. In case the master change your RedisClient connection will automatically connect to the new master server. If you are using a blocking client, you can use SentinelMonitoredRedisBlockingClient
Pool
RedisClientPool connect to a pool of redis servers. Redis commands are dispatched to redis connection in a round robin way.
Master Slave
RedisClientMasterSlaves connect to a master and a pool of slaves.
The write
commands are sent to the master, while the read commands are sent to the slaves in the RedisClientPool
Config Which Dispatcher to Use
By default, the actors in this project will use the dispatcher rediscala.rediscala-client-worker-dispatcher
. If you want to use another dispatcher, just config the implicit value of redisDispatcher
:
implicit val redisDispatcher = RedisDispatcher("akka.actor.default-dispatcher")
ByteStringSerializer ByteStringDeserializer ByteStringFormatter
case class DumbClass(s1: String, s2: String)
object DumbClass {
implicit val byteStringFormatter = new ByteStringFormatter[DumbClass] {
def serialize(data: DumbClass): ByteString = {
//...
}
def deserialize(bs: ByteString): DumbClass = {
//...
}
}
}
//...
val dumb = DumbClass("s1", "s2")
val r = for {
set <- redis.set("dumbKey", dumb)
getDumbOpt <- redis.get[DumbClass]("dumbKey")
} yield {
getDumbOpt.map(getDumb => {
assert(getDumb == dumb)
println(getDumb)
})
}
Full example: ExampleByteStringFormatter
Scaladoc
Rediscala scaladoc API (version 1.8)
Rediscala scaladoc API (version 1.7)
Rediscala scaladoc API (version 1.6)
Rediscala scaladoc API (version 1.5)
Rediscala scaladoc API (version 1.4)
Rediscala scaladoc API (version 1.3)
Rediscala scaladoc API (version 1.2)
Rediscala scaladoc API (version 1.1)
Rediscala scaladoc API (version 1.0)
Performance
More than 250 000 requests/second
The hardware used is a macbook retina (Intel Core i7, 2.6 GHz, 4 cores, 8 threads, 8GB) running the sun/oracle jvm 1.6
You can run the bench with :
- clone the repo
git clone git@github.com:etaty/rediscala.git
- run
sbt bench:test
- open the bench report
rediscala/tmp/report/index.html