Reactive Scala Driver for MongoDB

Asynchronous & Non-Blocking

Setup your project

We assume that you got a running MongoDB instance. If not, get the latest MongoDB binaries and unzip the archive. Then you can launch the database:

$ mkdir /path/to/data
$ /path/to/bin/mongod --dbpath /path/to/data

This will start a standalone MongoDB instance that stores its data in the data directory and listens on the TCP port 27017.

Set up your project dependencies

ReactiveMongo is available on Maven Central.

Using SBT, you just have to edit build.sbt and add the driver dependency:

libraryDependencies ++= Seq(
  "org.reactivemongo" %% "reactivemongo" % "0.1x"
)

for Pekko based projects, add the following dependency:

libraryDependencies ++= Seq(
  "org.reactivemongo" %% "reactivemongo-pekko" % "0.1x"
)

Or if you want to be on the bleeding edge using snapshots:

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

libraryDependencies ++= Seq(
  "org.reactivemongo" %% "reactivemongo" % "1.0.0-SNAPSHOT"
)

Akka dependency:

ReactiveMongo is internally using Akka, so it declares a transitive dependency to.

If your project already has the Akka dependency, directly or transitively (e.g. by Play dependencies), both must be compatible.

ReactiveMongo is tested against Akka from version 2.3.13 up to 2.4.x (2.4.8 for now).

Logging

SLF4J is now used by the ReactiveMongo logging, so a SLF4J binding must be provided (e.g. slf4j-simple).

In a Play application, the Play Framework logging will be used.

Example of logging configuration with the Logback binding:

<configuration>
  <conversionRule conversionWord="coloredLevel"
    converterClass="play.api.Logger$ColoredLevel" />

  <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%date %coloredLevel %logger - [%level] %message%n%xException</pattern>
    </encoder>
  </appender>

  <logger name="reactivemongo" level="WARN" />

  <root level="WARN">
    <appender-ref ref="STDOUT" />
  </root>
</configuration>

As Akka is used, so it can be useful to also configure its logging.

mongo-async-driver {
  akka {
    loggers = ["akka.event.slf4j.Slf4jLogger"]
    loglevel = DEBUG
  }
}

About Akka logging, also note that the dead letters logging can be safely ignored when the driver is closing (doesn’t indicate an issue).

log-dead-letters-during-shutdown = off can be added to previous configuration to disable the related debug (default since Akka 2.6).

Troubleshooting:

If the following error is raised, you need to make sure to provide a SLF4J binding (e.g. logback-classic).

NoClassDefFoundError: : org/slf4j/LoggerFactory

Log4J is still required for backward compatibility (by deprecated code). If you see the following message, please make sure you have a Log4J framework available.

ERROR StatusLogger No log4j2 configuration file found. Using default configuration: logging only errors to the console.

Next: Connect to the database

Suggest changes