Reactive Scala Driver for MongoDB

Asynchronous & Non-Blocking

ReactiveMongo 0.16.0 - Highlights

ReactiveMongo 0.16.0 – Release details

What’s new?

The documentation is available online, and its code samples are compiled to make sure it’s up-to-date.

The next release will be 1.0.0.

The impatient can have a look at the release slideshow.


This release is compatible with the following runtime.

MongoDB versions older than 2.6 are not longer supported by ReactiveMongo.

Recommended configuration:

The driver core and the modules are tested in a container based environment, with the specifications as bellow.

This can be considered as a recommended environment.

Connection options

The following options are deprecated:

SNI is now supported for the SSL connection.

The x.509 certificate authentication is now supported, and can be configured by setting x509 as authenticationMechanism, and with the following new options.

import reactivemongo.api._

def connection(driver: MongoDriver) =

The DNS seedlist is now supported, using mongodb+srv:// scheme in the connection URI.

import reactivemongo.api._

def seedListCon(driver: MongoDriver) =

Netty native

The internal Netty dependency has been updated to the version 4.1.

It comes with various improvements (memory consumption, …), and also to use Netty native support (kqueue for Mac OS X and epoll for Linux, on x86_64 arch).

See the documentation

Query and write operations

The collection API provides new operations.


The new insert operation is providing an InsertBuilder, which supports,

import scala.concurrent.Future

import reactivemongo.bson.BSONDocument
import reactivemongo.api.commands.{ MultiBulkWriteResult, WriteResult }
import reactivemongo.api.collections.bson.BSONCollection

val document1 = BSONDocument(
  "firstName" -> "Stephane",
  "lastName" -> "Godbillon",
  "age" -> 29)

// Simple: .insert[T].one(t)
def simpleInsert(coll: BSONCollection): Future[WriteResult] =
  coll.insert[BSONDocument](ordered = false).one(document1)

// Bulk: .insert[T].many(Seq(t1, t2, ..., tN))
def bulkInsert(coll: BSONCollection): Future[MultiBulkWriteResult] =
  coll.insert[BSONDocument](ordered = false).
  many(Seq(document1, BSONDocument(
    "firstName" -> "Foo",
    "lastName" -> "Bar",
    "age" -> 1)))


The new update operation returns an UpdateBuilder, which can be used to perform simple or bulk update.

import scala.concurrent.Future

import reactivemongo.bson.BSONDocument

import reactivemongo.api.collections.bson.BSONCollection

def update1(personColl: BSONCollection) = {
  val selector = BSONDocument("name" -> "Jack")

  val modifier = BSONDocument(
    "$set" -> BSONDocument(
      "lastName" -> "London",
      "firstName" -> "Jack"),
      "$unset" -> BSONDocument("name" -> 1))

  // Simple update: get a future update
  val futureUpdate1 = personColl.
    update(ordered = false).one(selector, modifier,
      upsert = false, multi = false)

  // Bulk update: multiple update
  val updateBuilder1 = personColl.update(ordered = true)
  val updates = Future.sequence(Seq(
      q = BSONDocument("firstName" -> "Jane", "lastName" -> "Doh"),
      u = BSONDocument("age" -> 18),
      upsert = true,
      multi = false),
      q = BSONDocument("firstName" -> "Bob"),
      u = BSONDocument("age" -> 19),
      upsert = false,
      multi = true)))

  val bulkUpdateRes1 = updates.flatMap { ops => updateBuilder1.many(ops) }


The .delete function returns a DeleteBuilder, to perform simple or bulk delete.

import scala.concurrent.Future

import reactivemongo.bson.BSONDocument

import reactivemongo.api.collections.bson.BSONCollection

def simpleDelete1(personColl: BSONCollection) =
  personColl.delete[BSONDocument](ordered = false).
    one(BSONDocument("firstName" -> "Stephane"))

def bulkDelete1(personColl: BSONCollection) = {
  val deleteBuilder = personColl.delete[BSONDocument](ordered = false)

  val deletes = Future.sequence(Seq(
      q = BSONDocument("firstName" -> "Stephane"),
      limit = Some(1), // former option firstMatch
      collation = None),
      q = BSONDocument("lastName" -> "Doh"),
      limit = None, // delete all the matching document
      collation = None)))

  deletes.flatMap { ops => deleteBuilder.many(ops) }

The .remove operation is now deprecated.

BSON library

The BSON library for ReactiveMongo has been updated.

More: BSON Library overview


The Decimal128 type introduced by MongoDB 3.4 is supported, as BSONDecimal, and can be read or write as java.math.BigDecimal.


A handler is now available to write and read Scala Map as BSON, provided the key and value types are themselves supported.

import reactivemongo.bson._

def bsonMap = {
  val input: Map[String, Int] = Map("a" -> 1, "b" -> 2)

  // Ok as key and value (String, Int) are provided BSON handlers
  val doc: BSONDocument = BSON.write(input)

  val output =[BSONDocument, Map[String, Int]](doc)


The compile-time option AutomaticMaterialization has been added, when using the macros with sealed family, to explicitly indicate when you want to automatically materialize required instances for the subtypes (if missing from the implicit scope).

sealed trait Color

case object Red extends Color
case object Blue extends Color
case class Green(brightness: Int) extends Color
case class CustomColor(code: String) extends Color

object Color {
  import reactivemongo.bson.Macros,
    Macros.Options.{ AutomaticMaterialization, UnionType, \/ }

  // Use `UnionType` to define a subset of the `Color` type,
  type PredefinedColor =
    UnionType[Red.type \/ Green \/ Blue.type] with AutomaticMaterialization

  val predefinedColor = Macros.handlerOpts[Color, PredefinedColor]

A new annotation @Flatten has been added, to indicate to the macros that the representation of a property must be flatten rather than a nested document.

import reactivemongo.bson.BSONDocument
import reactivemongo.bson.Macros.Annotations.Flatten

case class Range(start: Int, end: Int)

case class LabelledRange(
  name: String,
  @Flatten range: Range)

// Flattened with macro as bellow:
BSONDocument("name" -> "foo", "start" -> 0, "end" -> 1)

// Rather than:
// BSONDocument("name" -> "foo", "range" -> BSONDocument(
//   "start" -> 0, "end" -> 1))


There are newly supported by the Aggregation Framework.


The $addFields stage can now be used.

import scala.concurrent.ExecutionContext

import reactivemongo.api.collections.BSONCollection

def sumHomeworkQuizz(students: BSONCollection) =
  students.aggregateWith1[BSONDocument]() { framework =>
    import framework.AddFields

      "totalHomework" -> document(f"$$sum" -> f"$$homework"),
      "totalQuiz" -> document(f"$$sum" -> f"$$quiz"))) -> List(
        "totalScore" -> document(f"$$add" -> array(
        f"$$totalHomework", f"$$totalQuiz", f"$$extraCredit")))))


The $bucketAuto stage introduced by MongoDB 3.4 can be used as bellow.

import scala.concurrent.ExecutionContext

import reactivemongo.bson._
import reactivemongo.api.Cursor
import reactivemongo.api.collections.bson.BSONCollection

def populationBuckets(zipcodes: BSONCollection)(implicit ec: ExecutionContext) =
  zipcodes.aggregateWith1[BSONDocument]() { framework =>
    import framework.BucketAuto

    BucketAuto(BSONString(f"$$population"), 2, None)() -> List.empty
  }.collect[Set](Int.MaxValue, Cursor.FailOnError[Set[BSONDocument]]())


The $filter stage is now supported.


import reactivemongo.bson.{ BSONArray, BSONDocument, BSONString }

import reactivemongo.api.Cursor
import reactivemongo.api.collections.bson.BSONCollection

def salesWithItemGreaterThanHundered(sales: BSONCollection) =
  sales.aggregateWith1[BSONDocument]() { framework =>
    import framework._

    val sort = Sort(Ascending("_id"))

    Project(BSONDocument("items" -> Filter(
      input = BSONString(f"$$items"),
      as = "item",
      cond = BSONDocument(
        f"$$gte" -> BSONArray(f"$$$$item.price", 100))))) -> List(sort)

  }.collect[List](Int.MaxValue, Cursor.FailOnError[List[BSONDocument]]())


The $replaceRoot stage is now supported.

import scala.concurrent.Future

import reactivemongo.bson.BSONDocument

import reactivemongo.api.collections.bson.BSONCollection

/* For a fruits collection:
   "_id" : 1,
   "fruit" : [ "apples", "oranges" ],
   "in_stock" : { "oranges" : 20, "apples" : 60 },
   "on_order" : { "oranges" : 35, "apples" : 75 }
}, ...

def replaceRootTest(fruits: BSONCollection): Future[Option[BSONDocument]] = {
  fruits.aggregateWith1[BSONDocument]() { framework =>
    import framework._

    ReplaceRootField("in_stock") -> List.empty
  // Results: { "oranges": 20, "apples": 60 }, ...

More: Aggregation Framework


The operations to manage a MongoDB instance can be executed using ReactiveMongo. This new release has new functions for DB administration.


The DefaultDB has now a ping operation, to execute a ping command.

import scala.concurrent.Future

import reactivemongo.api.DefaultDB

def ping(admin: DefaultDB): Future[Boolean] =

Breaking changes

The Typesafe Migration Manager has been setup on the ReactiveMongo repository. It will validate all the future contributions, and help to make the API more stable.

For the current 0.16.0 release, it has detected the following breaking changes.

Test coverage


Operations and commands