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. Java support has been dropped. See details here: #22

Don't hesitate to ask questions in the Tepkin Google Group or join chat on Gitter:

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

Please read our Scala Guide first: https://github.com/fehmicansaglam/tepkin/wiki/Scala-Guide

Quick Start

Setting up dependencies

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

libraryDependencies ++= Seq(
  "net.fehmicansaglam" %% "tepkin" % "0.5"
)

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

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

libraryDependencies ++= Seq(
  "net.fehmicansaglam" %% "tepkin" % "0.6-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 net.fehmicansaglam.bson.BsonDsl._
import net.fehmicansaglam.bson.Implicits._
import net.fehmicansaglam.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 net.fehmicansaglam.bson.BsonDocument
import net.fehmicansaglam.bson.element.BsonElement
import net.fehmicansaglam.bson.BsonDsl._
import net.fehmicansaglam.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 net.fehmicansaglam.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 net.fehmicansaglam.bson.BsonDocument
import net.fehmicansaglam.bson.BsonDsl._
import net.fehmicansaglam.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 net.fehmicansaglam.bson.BsonDsl._
import net.fehmicansaglam.bson.Implicits._

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

Insert a collection of documents

import net.fehmicansaglam.bson.BsonDsl._
import net.fehmicansaglam.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 net.fehmicansaglam.bson.BsonDocument
import net.fehmicansaglam.bson.BsonDsl._
import net.fehmicansaglam.bson.Implicits._

import scala.collection.immutable.Iterable

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

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

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

Other queries

Update

import net.fehmicansaglam.bson.BsonDsl._
import net.fehmicansaglam.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 net.fehmicansaglam.bson.BsonDsl._
import net.fehmicansaglam.bson.Implicits._

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

Update and return the updated document.

import net.fehmicansaglam.bson.BsonDsl._
import net.fehmicansaglam.bson.Implicits._

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

Create index

import net.fehmicansaglam.bson.BsonDsl._
import net.fehmicansaglam.bson.Implicits._
import net.fehmicansaglam.tepkin.protocol.command.Index

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

Donations

Tepkin is a free software project and will always be. I work hard to make it stable and to add new features. I am always available if you encounter a problem and file an issue on Github. If you like Tepkin and find it helpful, you might give me a gift from some of the books (Kindle) I have in my wish list:

My Wish List on Amazon. Thanks!

One last thing, I am available for hire. If you think you know a job that is suitable for me, especially in Europe, please contact me at fehmican dot saglam at gmail dot com.

fehmicansaglam / tepkin 0.5