ReactiveMongo: a non-blocking MongoDB driver for Scala

A driver whose basic promise is that it never blocks

ReactiveMongo is described as a Scala driver that provides fully non-blocking and asynchronous I/O operations.

That single phrase describes both the purpose and the reason to care. A blocking MongoDB driver occupies a thread while it waits for the server, so the number of concurrent operations you can have is bounded by the size of your thread pool. A non-blocking driver returns a future instead, and the work continues on the driver's own threads.

The audience is therefore Scala services with many concurrent database conversations: a gateway fanning out to several collections, an event consumer, a service whose latency budget is measured in the low milliseconds. It is a much narrower audience than MongoDB itself, which has drivers for most languages, and it is worth being honest that the blocking Java driver is a perfectly reasonable choice for a lot of applications.

The topics attached to the repository line up with that: asynchronous, reactive, database, driver, mongodb, scala. The project is Apache-2.0 licensed, with the licence in LICENSE.txt and a separate NOTICE.txt beside it.

The project dates back far enough to have a well-established documentation site at reactivemongo.org, which the README points to for complete documentation, tutorials and samples, and there is a community help forum linked as well as the issue tracker.

The newest release tag is from 2020, the repository is not

The version history here needs careful reading, because two facts point in opposite directions.

The only listed release is 0.20.0, published on 2020-01-03. Meanwhile the last push to the repository was on 2026-10-13.

So the code is being changed regularly while the published artifact on Maven Central is years old. That is not necessarily neglect. A driver library has a stable API surface, and a project may well decide that the released version is good enough for production while the master branch absorbs fixes, dependency updates and changes for newer MongoDB server versions.

The repository layout supports that reading. There is a .scala-steward.conf, which is the configuration file for Scala Steward, a bot that opens pull requests to bump library dependencies. There is a .scalafmt.conf for formatting, a .scalafix.conf for lint rules, and a codestyle.sbt file. There is also a .git-blame-ignore-revs, a file used when a large reformatting commit should be excluded from blame history, which tells you that formatting and code movement are part of the recent history.

The practical consequence for an adopter: you are choosing between a published artifact that is six years old and a source build of master, and the README tells you how to do the latter, including the instructions to publish locally with SBT.

Adding the driver to a build.sbt

The documented usage starts with adding the dependency in build.sbt, and the snippet is deliberately minimal, with the version left as a placeholder.

libraryDependencies ++= Seq(
  "org.reactivemongo" %% "reactivemongo" % "VERSION"
)

The %% operator is the Scala.js style cross version suffix, so the same declaration resolves to a Scala 2.13 artifact for a 2.13 build and a different one for a 2.12 build.

The README does not tell you which version string to use, which is a deliberate omission given the point above about the release situation. The Maven Central badge in the README points at the 2.13 artifact, org.reactivemongo/reactivemongo_2.13, and the Javadoc badge links to the matching javadoc.io entry, so those two links are the practical way to find the versions that exist and the API of each.

That is the whole installation story for a normal user. There is no driver to install, no server to configure, and no code generation step. You add the library, create a connection against your MongoDB deployment, and use the driver API for the document model and the collection operations. The reference documentation lives on the project website rather than in the repository, which is typical for a library whose documentation is versioned separately from its source.

Building from source means cloning and running sbt

The README offers a manual build for anyone who wants the latest improvements and fixes. You need a Git client and SBT.

$ git clone [email protected]:ReactiveMongo/ReactiveMongo.git

Then move into the ReactiveMongo directory and start the SBT build console.

$ cd ReactiveMongo
$ sbt
> +publishLocal

The +publishLocal command is the interesting one. The plus prefix asks SBT to run the task across all the cross built Scala versions in the build, and publishLocal installs the resulting artifacts into your local Ivy or Maven cache rather than to a public repository. In other words, after this you can depend on the freshly built version from another project on the same machine as if it had been released.

That flow is the reason the README pushes this path at all. It is how you consume a driver version that has not been published, and how you work on the library itself.

The build is defined in build.sbt with a project directory and a version.sbt holding the version, and the modules mirror the package structure: core, driver, test, tools, and two actor integration modules.

The test environment needs file descriptor headroom

Running the tests is described in one line, and then qualified by a warning that is worth taking seriously.

sbt testOnly

The qualification says the test environment must be able to handle the maximum number of incoming connections for the MongoDB instance, and that this must be checked and eventually updated using ulimit -n.

That is a real operational detail rather than boilerplate. A non-blocking driver opens a lot of connections, and a suite that spins up many clients against a local MongoDB will hit the per process descriptor limit long before it hits a memory limit. When a test run fails with an unhelpful error about sockets or connections, this is the first thing to check, and the fix is to raise the open file limit for the shell running the tests.

The other half of testing is the CI setup. The README links a CircleCI badge, and to reproduce a CI build locally it points at the Docker tools in the repository, under tools/docker, with its own README. That is the difference between a build you can trust and a build you can only hope matches: you can bring up the same containerised environment the pipeline uses.

One more badge is worth reading honestly. The coverage badge shows 60% and points at the coverage report for version 0.12.7, so the published figure describes an old release rather than the current tree, and it is not a high number in any case.

Two actor modules, Akka and Pekko

The repository contains actors-akka and actors-pekko as separate modules.

The split reflects a real fork in the Scala ecosystem. Akka changed its licence in recent versions, and the Pekko project is the community continuation, so a library that wants to support both has to ship against both. Having both directories means ReactiveMongo covers whichever actor system you are on rather than forcing a choice.

For a team deciding whether to use the driver, this is a small but meaningful signal about the state of the project. It means the maintainers are tracking the ecosystem rather than sitting on one side of a split, and it also means the actor integration is a separate opt in artifact, so you can use the core driver without pulling an actor framework into your dependency set at all.

The rest of the tree follows the same modular shape: core for the shared pieces, driver for the main implementation, test for the test code, and tools for the build and CI helpers, including the Docker directory used to reproduce a CI build. There is also a project directory, which is where SBT keeps its own build definitions, and a .jvmopts file that sets JVM options for the build itself.

Licensing is Apache-2.0, and contributions have their own rules

The licensing position is straightforward. The project is Apache-2.0, with LICENSE.txt and NOTICE.txt in the repository root, and the description identifies it as the ReactiveMongo driver for MongoDB under the ReactiveMongo organisation.

The NOTICE file is the part that gets skipped, and in a driver it is not decorative. A MongoDB driver ships code that interfaces with a server and often bundles or derives from protocol specifications, and the notices file records what has to be attributed. If you redistribute a driver in a product, read NOTICE.txt rather than assuming the Apache-2.0 grant is the whole story.

Contributions are governed by their own document. The README links the ReactiveMongo developer and contributor guidelines in CONTRIBUTING.md, and the repository also carries a CODE_OF_CONDUCT.md. Both exist because the project is a long lived community effort rather than a single team project, which matches the governance implied by the separate documentation site, the Google group for help, the issue tracker and the samples referenced from the website.

The last push to the repository was on 2026-10-13, so the code is current even though the newest tag is 0.20.0 from 2020-01-03. For a team willing to build from source, that combination is workable. For a team that wants a versioned dependency with a changelog, it is the first thing to raise with your team.

Editorial conclusion

ReactiveMongo suits a Scala service with a high number of concurrent MongoDB connections, where a blocking driver would tie up request threads, and the library is a mature choice for that specific shape of workload. It does not suit a team starting a new project that wants a driver with regular tagged releases, since the newest release tag on record is 0.20.0 from 2020-01-03 even though the repository was pushed to on 2026-10-13, so you would be building from source and tracking master. Before you commit, check the documentation at reactivemongo.org for the version you would actually consume, decide whether the Akka or Pekko actor module fits your stack, and confirm the file descriptor limits on your test machines, because the README warns that the test environment must handle the maximum number of incoming connections for the MongoDB instance.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. ReactiveMongo/ReactiveMongo on GitHub
4. README
5. Releases