# mongodb/mongo-java-driver: the official MongoDB driver for JVM applications
> The official MongoDB driver for Java, Kotlin, and Scala ships as separate artifacts for synchronous, reactive, and coroutine use. This is what the repository actually contains, how to get the dependency into a build, and where the driver stops being the right tool.
**mongodb/mongo-java-driver** — The official MongoDB drivers for Java, Kotlin, and Scala
- Repository: https://github.com/mongodb/mongo-java-driver
- Website: https://www.mongodb.com/docs/drivers/java/sync/current/
- Stars: 2,662 · Forks: 1,500
- Language: Java
- License: Apache-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/mongodb-mongo-java-driver
## What the driver is and which JVM application it fits
MongoDB speaks a wire protocol over TCP. Your Java code does not. The driver is the translation layer: it opens connections, negotiates with the server, serialises your objects into BSON, and hands back results. mongodb/mongo-java-driver is the official implementation of that layer for the JVM, published by MongoDB under Apache-2.0.
The repository is not one library. The top-level entries list driver-sync, driver-reactive-streams, driver-kotlin-coroutine, driver-kotlin-sync, driver-scala, driver-legacy, and driver-lambda, plus bson and the codec modules (bson-kotlin, bson-kotlinx, bson-record-codec, bson-scala). Each is a separate artifact with its own API surface. A Spring Boot service that blocks on database calls wants driver-sync. A service built on Project Reactor or RxJava wants driver-reactive-streams. A Kotlin service using suspend functions wants driver-kotlin-coroutine. Picking the wrong one means either wrapping blocking calls in a thread pool or rewriting data access later.
The audience is narrower than the topic list suggests. This is infrastructure for people who are comfortable choosing between a blocking and a non-blocking client, and who understand that a connection pool is a shared resource. If you want an object mapper with a schema, this is the wrong layer.
## How a query actually flows through driver-sync
The mechanism is easiest to see in the synchronous driver. You construct a MongoClient, which owns a connection pool and a background monitor per server. From it you get a MongoDatabase, then a MongoCollection typed to a document class. A call such as find or insertOne borrows a connection from the pool, encodes the request into BSON using the codec registry, writes it to the socket, waits for the reply, and decodes the response back into your type.
The codec registry is the part that surprises newcomers. The driver does not reflect over your class on every call; it looks up a CodecProvider for the target type and caches the result. Plain documents map to org.bson.Document. POJOs map through the POJO codec, which needs conventions or annotations to decide how fields become BSON keys. Kotlin data classes go through bson-kotlin, and kotlinx.serialization types through bson-kotlinx. The module you add to your build determines what the registry can encode without extra configuration.
Two constraints follow from this design. First, the client is expensive to create and cheap to reuse; the README's support section asks for the exact MongoClient construction line when reporting connectivity issues, which tells you the constructor arguments are where most problems live. Second, anything under com.mongodb.internal.* is private. The README states that code in those packages can change at any time, so a helper you copy from there is a future upgrade failure.
## Adding the driver with Maven and what the build requires
The README points to Sonatype Central for binaries and dependency information, and gives the Maven coordinates for the synchronous driver. The version is a placeholder in the README itself, so check the release notes for the current number before pasting this into a build file. The repository's recent releases include 5.12.0.
```xml
org.mongodb
mongodb-driver-sync
x.y.z
```
For a Kotlin coroutine service the equivalent artifact is driver-kotlin-coroutine, and for reactive streams it is driver-reactive-streams. The groupId stays org.mongodb in each case. Adding the sync artifact alone gives you a blocking client plus the BSON library it depends on.
The README also documents snapshot builds for people who need an unreleased change. Snapshots are published via Sonatype, and the README gives the repository block to add, with releases disabled and snapshots enabled.
```xml
Central Portal Snapshots
central-portal-snapshots
https://central.sonatype.com/repository/maven-snapshots/
false
true
```
What you should see after a build is the driver and BSON on the classpath. The README does not include a connection example, so the first call to MongoClients.create and the first query are documented in the linked Java driver reference rather than in the repository.
## Building the driver from source and the test suite's server requirement
Most teams consume the driver as a dependency and never build it. If you do need to build it, the README is explicit about the toolchain: Java 17+ and git. The build is Gradle, driven by the wrapper in the repository.
```bash
$ git clone --recurse-submodules https://github.com/mongodb/mongo-java-driver.git
$ cd mongo-java-driver
$ ./gradlew check
```
The --recurse-submodules flag is not optional decoration; the repository has a .gitmodules entry, so a plain clone leaves parts of the tree missing. The check task runs the test suite, and that suite expects a live mongod. The README gives the exact invocation, including the enableTestCommands parameter that the tests rely on.
```bash
$ mkdir -p data/db
$ mongod --dbpath ./data/db --logpath ./data/mongod.log --port 27017 --logappend --fork --setParameter enableTestCommands=1
```
The README also warns that "Too many open files" errors during the test run mean the file descriptor limit is too low, and points to MongoDB's ulimit documentation. That is a real friction point: the suite opens many connections, and a default container limit will fail it before any test logic runs. Note the port, 27017, because the tests assume the default unless configured otherwise.
The README adds IntelliJ-specific setup notes, including unticking the "Use '--release' option for cross-compilation (Java 9 and later)" compiler setting when a build fails with a missing javax.net.ssl.SNIHostName symbol.
## Where the driver is the wrong tool
The driver is a transport and codec library, not a data access framework. It has no schema, no migrations, no lazy loading, and no unit-of-work. If your team expects repository interfaces generated from entity classes, Spring Data MongoDB sits on top of this driver and provides that; using the driver directly means writing those abstractions yourself.
The stability annotations are the second boundary. The README defines @Alpha as APIs subject to incompatible changes or removal, with no compatibility guarantees, and says it is inadvisable for applications to use them in production or for libraries to depend on them. @Beta APIs can be modified or removed at any time. @Deprecated APIs stay supported until the next major release, which sets a deadline rather than removing the problem. A feature you need may exist only behind one of these annotations, and the README's own guidance is to keep it out of production code.
There is also a versioning boundary. The driver follows semantic versioning, so a major bump can break source compatibility. The README does not document a rollback procedure for an upgrade that goes wrong, and it does not describe a compatibility matrix between driver versions and server versions; that information lives in the linked documentation rather than in the repository. Teams that pin one driver version across many services should confirm server compatibility against that documentation before treating an upgrade as routine.
## How the driver differs from a Kotlin-first client
The most direct alternative for JVM teams is KMongo, a community wrapper that layers Kotlin-idiomatic extensions over the official driver. The difference in approach is architectural rather than cosmetic. KMongo does not implement the wire protocol; it delegates to mongodb-driver-sync or the reactive driver underneath and adds Kotlin syntax, serialisation hooks, and helper extensions. The official driver-kotlin-coroutine module instead builds a suspend-function API directly on the reactive streams implementation, so coroutine cancellation propagates through the driver's own async machinery rather than through a wrapper.
That distinction decides the trade-off. Choosing KMongo means your upgrade path depends on a third party tracking MongoDB's releases, and a driver release can land before the wrapper supports it. Choosing driver-kotlin-coroutine means accepting the official API's shape, which the README marks with the same stability policy as the rest of the repository. Neither is universally better; the question is whether you want the wrapper's ergonomics or the vendor's release cadence.
For teams already on Spring, the real comparison is not KMongo at all but Spring Data MongoDB, which wraps this driver and adds mapping, repositories, and lifecycle integration. Reaching for the driver directly inside a Spring application usually means you wanted the lower-level control and accepted the extra code.
## Licence, maintenance, and the cost of staying current
The repository is licensed under Apache-2.0 and includes a LICENSE.txt at the top level plus a THIRD-PARTY-NOTICES file. Apache-2.0 permits commercial and closed-source use and requires that you preserve notices; the THIRD-PARTY-NOTICES file is where the driver records the terms of what it bundles. If your organisation runs a licence scan, that file is the one to feed it. None of this is legal advice, and the driver's own notices should be checked against your policy.
Maintenance is active by the only measures available here: the repository is not archived, and the last push was on 2026-09-24. Releases have been frequent, with 5.12.0 on 2026-09-17, 5.11.1 on 2026-09-10, and 5.11.0 on 2026-08-28. That cadence cuts both ways. Patch releases arrive quickly, but so do minor releases, and each one is a dependency bump you either take or postpone.
The upgrade cost is concentrated in three places: any code touching com.mongodb.internal.*, any use of @Alpha or @Beta APIs, and any use of @Deprecated methods that will disappear at the next major version. A codebase that avoids all three can move between minor versions with little more than a version string change. One that does not will discover the cost during the upgrade rather than before it. The repository also carries an AGENTS.md file and a scripts/sync-claude-md.sh script for keeping AI agent instructions in sync, which is a maintenance detail rather than an API concern.
## Conclusion
Adopt mongodb/mongo-java-driver when your application is a JVM service talking to MongoDB and you want the driver the server team ships, under Apache-2.0 with a documented stability policy. Do not adopt it if you need an object mapper with schema validation, or if your workload is a short-lived function where connection pool warm-up dominates; driver-lambda exists for that shape, but the README does not describe its tuning. Verify first that the artifact you pick matches your threading model (driver-sync, driver-reactive-streams, or driver-kotlin-coroutine), that your build targets Java 17 or later for compiling the driver itself, and that no code you depend on reaches into com.mongodb.internal.*, which the README states can change at any time.
## FAQ
### What is a MongoDB driver?
It is the client library that translates application calls into MongoDB's wire protocol and back. mongodb/mongo-java-driver is the official driver for Java, Kotlin, and Scala on the JVM, published under Apache-2.0.
### How can I connect to MongoDB using Java?
Add the mongodb-driver-sync artifact from org.mongodb to your build, then create a client and select a database and collection; the README links to the Java driver reference documentation at mongodb.com/docs/drivers/java/sync/current/ for the full API, and says to include the exact MongoClient construction line when reporting connectivity issues.
### What is MongoDB used for?
The driver repository documents the client library rather than the server's use cases, so this question is not answered by the README. The README points to MongoDB University and the Developer Center for tutorials on using the JVM drivers.
### What is the Python driver for MongoDB?
This repository is the Java, Kotlin, and Scala driver for the JVM and does not document a Python driver. Its documentation links cover the Java, Kotlin, and Scala drivers only.
## Sources
- [License: Apache-2.0](https://github.com/mongodb/mongo-java-driver/blob/main/LICENSE)
- [mongodb/mongo-java-driver on GitHub](https://github.com/mongodb/mongo-java-driver)
- [Project website](https://www.mongodb.com/docs/drivers/java/sync/current/)
- [README](https://github.com/mongodb/mongo-java-driver/blob/main/README.md)
- [Releases](https://github.com/mongodb/mongo-java-driver/releases)
---
Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mongodb-mongo-java-driver