DOCSEARCHbyAlgolia
Submit Docs

MongoDB Java Driver

repository·main·Indexed 25 days ago

https://github.com/mongodb/mongo-java-driver

Official connectivity for Java, Kotlin, and Scala applications to interact with MongoDB databases. The project includes the Java Driver (Sync), Kotlin Driver (Coroutine), and the Mongo Scala Driver, which provides Scala-idiomatic wrappers for the Mongo Reactive Streams driver and the Java Bson library. It supports Scala versions 2.11, 2.12, 2.13, and 3, and provides tools for GraalVM native image builds.

Tokens
3K
Snippets
10
Records
23
Agent score
82%

What's inside mongo-java-driver

  4. Install the MongoDB Java Driver via Maven

    main

    To use the MongoDB Java driver in a Maven project, add the mongodb-driver-sync dependency to your pom.xml. You can find dependency information and binaries on Sonatype Central.

    <dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-sync</artifactId>
    <version>x.y.z</version>
</dependency>

  5. Run Scala tests for specific versions

    main

    By default, tests run against Scala 2.13. You can use the -PscalaVersion flag to run tests against a different Scala version, or the -PjavaVersion flag to target a specific Java version. Use the :driver-scala:scalaCheck task to execute these tests.

    # Test driver-scala with Scala 3
./gradlew :driver-scala:scalaCheck -PscalaVersion=3

# Test driver-scala with Scala 2.12
./gradlew :driver-scala:scalaCheck -PscalaVersion=2.12

# Test driver-scala with the default (2.13) against Java 8
./gradlew :driver-scala:scalaCheck -PjavaVersion=8

  6. Configure IntelliJ IDEA for Driver Development

    main

    If you are developing using IntelliJ IDEA, follow these steps to avoid common build errors:

    Fix: java: cannot find symbol: class SNIHostName location: package javax.net.ssl

    • Go to Settings/Preferences > Build, Execution, Deployment > Compiler > Java Compiler.
    • Untick Use '--release' option for cross-compilation (Java 9 and later).

    Fix: java: package com.mongodb.internal.build does not exist Choose one of the following:

    1. Run the generateBuildConfig task: ./gradlew generateBuildConfig or via the Gradle tool window (driver-core > Tasks > buildconfig > generateBuildConfig).
    2. Configure the task to run automatically: In the Gradle tool window, right-click generateBuildConfig and select Execute Before Build.
    3. Delegate all build actions to Gradle: Go to Settings/Preferences > Build, Execution, Deployment > Build Tools > Gradle and set Build and run using and Run tests using to Gradle.

  7. Run tests for specific Scala versions

    main

    By default, tests run against Scala 2.13. To run the scalaCheck task against a specific Scala version, use the -PscalaVersion Gradle flag.

    # Test bson-scala with Scala 3
./gradlew :bson-scala:scalaCheck -PscalaVersion=3

# Test bson-scala with Scala 2.12
./gradlew :bson-scala:scalaCheck -PscalaVersion=2.12

# Test bson-scala with the default (2.13)
./gradlew :bson-scala:scalaCheck

  8. Collect and update reachability metadata

    main

    If the application build fails, you may need to collect reachability metadata and update the stored files. Run this sequence to clean the project, run the application with the agent to collect metadata, and then copy the metadata files.

    env JAVA_HOME="${JDK17}" ./gradlew clean && env JAVA_HOME=${JDK21_GRAALVM} ./gradlew -PincludeGraalvm -PjavaVersion=21 -Pagent :graalvm-native-image-app:run && env JAVA_HOME=${JDK21_GRAALVM} ./gradlew -PincludeGraalvm :graalvm-native-image-app:metadataCopy

  9. Build the Driver from Source

    main

    To build and compile the driver, you need Java 17+ and git.

    1. Clone the repository with submodules:
      git clone --recurse-submodules https://github.com/mongodb/mongo-java-driver.git
cd mongo-java-driver
    2. Run the Gradle check task:
      ./gradlew check

    Note for Tests: The test suite requires a running mongod instance configured with enableTestCommands=1. You can start a compatible instance using:

    mkdir -p data/db
mongod --dbpath ./data/db --logpath ./data/mongod.log --port 27017 --logappend --fork --setParameter enableTestCommands=1

    If you encounter "Too many open files" errors during testing, increase your system's available file descriptors (see ulimit documentation).

    $ git clone --recurse-submodules https://github.com/mongodb/mongo-java-driver.git
$ cd mongo-java-driver
$ ./gradlew check

  10. Configure Spotless for Scala 3 code

    main

    By default, Spotless uses Scala 2.13 formatting rules. If you are writing Scala 3 specific code, you must configure Spotless to use a Scala 3 scalafmt configuration targeting only the **/scala-3/** directory.

    Example configuration for build.gradle.kts:

    if (scalaVersion.equals("3")) {
    spotless {
        scala {
            clearSteps()
            target("**/scala-3/**")
            scalafmt("3.10.7").configFile(rootProject.file("config/scala/scalafmt-3.conf"))
        }
    }
}

  12. Prepare the environment for GraalVM native image builds

    main

    To build the graalvm-native-image-app using GraalVM native image, you must install GraalVM for JDK 21 Community. This version is required to allow specific Gradle toolchain specifications that match only GraalVM. You can install it via SDKMAN!.

    After installation, configure environment variables to point to your JDKs. For example, if your Gradle runner uses JDK 17 and your GraalVM uses JDK 21, export them as follows: