The MongoDB Atlas SQL JDBC Driver provides SQL connectivity to MongoDB Atlas for client applications developed in Java.
See the Atlas SQL Documentation for more information.

MongoDB Atlas SQL JDBC is a JDBC Type 4 driver compatible with the JDBC 4.2 specification.

MongoDB Atlas SQL JDBC driver requires Java 1.8 or higher.

You can download the precompiled driver (jars) from Maven Central.
Choose jar in the Download dropdown for the lean jar (dependencies not included) or all.jar for the fat jar (dependencies bundled inside the jar). The name of the driver class is com.mongodb.jdbc.MongoDriver.

To verify the integrity of the JDBC Driver packages, follow the steps below:

1. Import the Public Key:

• The public key ID is BDDC8671F1BE6F4D5464096624A4A8409351E954.
• To import the key, run the following command: gpg --keyserver <server url> --recv-keys BDDC8671F1BE6F4D5464096624A4A8409351E954.
• Replace <server url> with one of the current GPG Keyservers supported by Maven Central Servers:
  • keyserver.ubuntu.com
  • keys.openpgp.org
  • pgp.mit.edu

2. Verify Artifact:

• Download the artifact you want to verify along with the matching detached signature (.asc) file from Maven Central.
  • For example, mongodb-jdbc-2.2.2.jar and mongodb-jdbc-2.2.2.jar.asc.
• To verify the signature, run the following command gpg --verify <detached_signature_file> <artifact_to_verify>.
  • For example, gpg --verify mongodb-jdbc-2.2.2.jar.asc mongodb-jdbc-2.2.2.jar.

The connection URL is based on MongoDB connection string and has the jdbc: prefix. The general format for the connection URL is as follows, with items in square brackets ([ ]) being optional:

jdbc:mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?option1=value1[&option2=value2]...]

For more details :

• URI format: https://www.mongodb.com/docs/manual/reference/connection-string/
• Supported options: https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-connection-options

• Special characters in the JDBC url have to be URL encoded.
• The driver can not connect to a mongod instance, only to MongoDB Atlas.

All connection options can also be specified through a Properties object parameter instead of the being directly in the URL. However, if an option is in both the URL and the Properties object, the connection will fail.

In addition to the standard MongoDB connection options there are a number of additional properties specific to the JDBC driver.
These properties can only be specified using an additional Properties object parameter and not in the URL.

The following example demonstrates how to open a connection specifying :

• The standard options user and password via a Properties object and ssl and authSource via the URL.
• The JDBC specific options database (mandatory) and loglevel via a Properties object.

         java.util.Properties p = new java.util.Properties();
         p.setProperty("user", "user");
         p.setProperty("password", "foo");
         p.setProperty("database", "test");
         p.setProperty("loglevel", Level.SEVERE.getName());
         System.out.println("Connecting to database test...");
         Connection conn = DriverManager.getConnection("mongodb://mydatalake-xxxx.a.query.mongodb.net/?ssl=true&authSource=admin", p);

To build and test the driver run the following commands from root dir.

./gradlew clean build

./gradlew clean :demo:run

./gradlew clean :sourceJar

You can find the generated jar in build/libs/

./gradlew clean :shadowJar

You can find the generated jar in build/libs/

./gradlew clean :testJar

You can find the generated jar in build/libs/

./gradlew clean test

./gradlew spotlessApply

The driver requires the mongosqltranslate library for direct cluster SQL translation. For initial gradle builds the library files will be automatically downloaded to the cache directory ${project.rootDir}/.library_cache/. If a specific version of the library already exists in the cache, it will be used.

By default, the snapshot version will be downloaded. To use a specific version, use the libmongosqltranslateVersion property:

./gradlew clean build -PlibmongosqltranslateVersion=1.0.0-beta-1

Unless the updateLibs property is set to true, cached versions will be used to avoid repeated downloads.

# Override cached versions
./gradlew clean build -PupdateLibs=true

./gradlew downloadLibMongosqlTranslate

Integration testing requires a local MongoDB and Atlas Data Federation instance to be running

ADF_TEST_LOCAL_USER: Local ADF username
ADF_TEST_LOCAL_PWD: Local ADF password
ADF_TEST_LOCAL_AUTH_DB: Local ADF authentication database
HAVE_LOCAL_MONGOHOUSE: "1" if using local mongohouse source
LOCAL_MONGOHOUSE_DIR: Path to local mongohouse source

MDB_TEST_LOCAL_PORT (Optional): Local MongoDB port

./gradlew runDataLoader

./gradlew runTestGenerator

run_adf.sh is a helper script that will start a local mongod and Atlas Data Federation instance, used for integration testing.

./resources/run_adf.sh start

./resources/run_adf.sh stop

Use the SKIP_RUN_ADF option to skip the start and stop operations for those managing their own local instances.

export SKIP_RUN_ADF=1