Deprecation Notice

This project has moved to https://github.com/jeroenr/tepkin

Tepkin

Reactive MongoDB Driver for Scala built on top of Akka IO and Akka Streams.

Only MongoDB 2.6+, Scala 2.11+ is supported.

Contributions

Tepkin is a young but very active project and absolutely needs your help. Good ways to contribute include:

• Raising bugs and feature requests
• Fixing bugs
• Improving the performance
• Adding to the documentation

Quick Start

Setting up dependencies

Latest stable Tepkin release is 0.7 and is available on Maven Central. Just add the following dependency:

libraryDependencies ++= Seq(
  "com.github.jeroenr" %% "tepkin" % "0.7"
)

Or if you want to be on the bleeding edge using snapshots, latest snapshot release is 0.8-SNAPSHOT. Add the following repository and dependency:

resolvers += "Sonatype Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots/"

libraryDependencies ++= Seq(
  "com.github.jeroenr" %% "tepkin" % "0.8-SNAPSHOT"
)

Scala API

Working with BSON DSL

To construct a Bson document, you can either create BsonElements and join them with ~ or create a document directly.

import com.github.jeroenr.bson.BsonDsl._
import com.github.jeroenr.bson.Implicits._
import com.github.jeroenr.bson.element.BsonObjectId
import org.joda.time.DateTime

// Construct a BsonDocument from BsonElements
val element = "name" := "Johny"
val document = element ~
  ("surname" := "Doe") ~
  ("age" := 28) ~
  ("months" := $array(1, 2, 3))

// Construct a BsonDocument
val document = $document(
  "_id" := BsonObjectId.generate,
  "name" := "Johny",
  "surname" := "Doe",
  "age" := 28,
  "months" := $array(1, 2, 3),
  "details" := $document(
    "salary" := 455.5,
    "inventory" := $array("a", 3.5, 1L, true),
    "birthday" := new DateTime(1987, 3, 5, 0, 0)
  )
)

There is an implicit conversion from any BsonElement to BsonDocument for convenience.

import com.github.jeroenr.bson.BsonDocument
import com.github.jeroenr.bson.element.BsonElement
import com.github.jeroenr.bson.BsonDsl._
import com.github.jeroenr.bson.Implicits._

val element: BsonElement = "name" := "fehmi"
val document: BsonDocument = "name" := "fehmi"

Connecting to MongoDB

To make a connection to MongoDB, use the MongoClient interface.

import com.github.jeroenr.tepkin.MongoClient

// Connect to a MongoDB node.
val client = MongoClient("mongodb://localhost")

MongoClient manages multiple connection pools to MongoDB instances and therefore is a heavy class. Most of the time you will need only one MongoClient instance per application.

Use MongoDatabase and MongoCollection in order to obtain a reference to a database and a collection.

// Obtain a reference to the "tepkin" database
val db = client("tepkin")

// Obtain a reference to the "example" collection in "tepkin" database.
val collection = db("example")

MongoDatabase and MongoCollection are lightweight classes and may be instantiated more than once if needed. However they are both immutable and reusable.

All methods in the MongoCollection class need an implicit scala.concurrent.ExecutionContext and an akka.util.Timeout. You can define a default timeout and use the client's execution context as shown below:

import akka.util.Timeout
import scala.concurrent.duration._

// val client = ...

import client.ec
implicit val timeout: Timeout = 5.seconds

Find documents

import com.github.jeroenr.bson.BsonDocument
import com.github.jeroenr.bson.BsonDsl._
import com.github.jeroenr.bson.Implicits._

val query: BsonDocument = "name" := "fehmi"

val source = collection.find(query)

All find methods in Tepkin return an akka.stream.scaladsl.Source[List[BsonDocument], ActorRef]. Then you can use any method in Akka Streams to process the returned stream.

Insert operations

Insert a single document

import com.github.jeroenr.bson.BsonDsl._
import com.github.jeroenr.bson.Implicits._

val document = ("name" := "fehmi") ~ ("surname" := "saglam")
collection.insert(document)

Insert a collection of documents

import com.github.jeroenr.bson.BsonDsl._
import com.github.jeroenr.bson.Implicits._

val documents = (1 to 100).map(i => $document("name" := s"fehmi$i"))
collection.insert(documents)

Insert a large number of documents from a stream

import akka.stream.ActorFlowMaterializer
import akka.stream.scaladsl.Source
import com.github.jeroenr.bson.BsonDocument
import com.github.jeroenr.bson.BsonDsl._
import com.github.jeroenr.bson.Implicits._

import scala.collection.immutable.Iterable

implicit val mat = ActorFlowMaterializer()(client.context)

val documents: Source[List[BsonDocument], akka.NotUsed] = Source {
  Iterable.tabulate(100) { _ =>
    (1 to 1000).map(i => $document("name" := s"fehmi$i")).toList
  }
}

collection.insertFromSource(documents).runForeach(_ => ())

Other queries

Update

import com.github.jeroenr.bson.BsonDsl._
import com.github.jeroenr.bson.Implicits._

import scala.concurrent.Future

val document = ("name" := "fehmi") ~ ("surname" := "saglam")

val result: Future[UpdateResult] = for {
  insert <- collection.insert(document)
  update <- collection.update(
    query = "name" := "fehmi",
    update = $set("name" := "fehmi can")
  )
} yield update

Find and update

Update and return the old document.

import com.github.jeroenr.bson.BsonDsl._
import com.github.jeroenr.bson.Implicits._

collection.findAndUpdate(
  query = Some("name" := "fehmi"),
  update = $set("name" := "fehmi can")
)

Update and return the updated document.

import com.github.jeroenr.bson.BsonDsl._
import com.github.jeroenr.bson.Implicits._

collection.findAndUpdate(
  query = Some("name" := "fehmi"),
  update = $set("name" := "fehmi can"),
  returnNew = true
)

Create index

import com.github.jeroenr.bson.BsonDsl._
import com.github.jeroenr.bson.Implicits._
import com.github.jeroenr.tepkin.protocol.command.Index

collection.createIndexes(Index(name = "name_surname", key = ("name" := 1) ~ ("surname" := 1)))