SQL Interface Driver Setup

Download the MongoDB JDBC driver.

Download the latest JDBC driver from the MongoDB download center.

Move the jar file to the appropriate directory for your operating system.

Copy the jar file to the appropriate directory for your BI tool. For example, if you're installing the JDBC driver for Tableau:

• Windows: C:\Program Files\Tableau\Drivers

• macOS: ~/Library/Tableau/Drivers

• Linux: /opt/tableau/tableau_driver/jdbc

Verify the integrity of the downloaded package.

The MongoDB release team digitally signs all software packages to certify that a particular MongoDB package is a valid and unaltered MongoDB release. MongoDB signs each release branch with a different PGP key in .asc format.

1. Run the following command to download the .asc file from the Maven Central Repository. Replace <versionNumber> with the version of the driver you downloaded and <artifactToVerify> with the name of the file you downloaded.

   curl -O https://repo1.maven.org/maven2/org/mongodb/mongodb-jdbc/<versionNumber>/<artifactToVerify>.asc

   For example, if you downloaded mongodb-jdbc-2.2.3-all.jar, you would run the following command.

   curl -O https://repo1.maven.org/maven2/org/mongodb/mongodb-jdbc/2.2.3/mongodb-jdbc-2.2.3-all.jar.asc

2. Run the following command to download then import the key file. Replace <serverUrl> with one of the current GPG key servers supported by Maven:

   • keyserver.ubuntu.com

   • keys.openpgp.org

   • pgp.mit.edu

   gpg --keyserver <serverUrl> --recv-keys BDDC8671F1BE6F4D5464096624A4A8409351E954

   HIDE OUTPUT

   gpg: key BDDC8671F1BE6F4D5464096624A4A8409351E954: public key "MongoDB JDBC Driver Release Signing Key <packaging@mongodb.com>" imported
   gpg: Total number processed: 1
   gpg:               imported: 1

3. Run the following command to verify the MongoDB JDBC driver installation file. Replace <detachedSignatureFile> and <artifactToVerify> with the names of the files you downloaded.

   gpg --verify <detachedSignatureFile> <artifactToVerify>

   For example, if you downloaded mongodb-jdbc-2.2.3-all.jar and mongodb-jdbc-2.2.3-all.jar.asc to your current directory, you would run the following.

   gpg --verify mongodb-jdbc-2.2.3-all.jar.asc mongodb-jdbc-2.2.3-all.jar

   GPG should return a response similar to the following:

   gpg: Signature made Wed May 22 13:24:36 2024 MDT
   gpg:                using RSA key BDDC8671F1BE6F4D5464096624A4A8409351E954
   gpg: Good signature from "MongoDB JDBC Driver Release Signing Key <packaging@mongodb.com>"

   If the package is properly signed, but you don't yet trust the signing key in your local trustdb, gpg will also return the following message:

   gpg: WARNING: This key is not certified with a trusted signature!
   gpg:          There is no indication that the signature belongs to the owner.
   Primary key fingerprint: D2C4 5B7E 66A5 DCA1 8B76  57A8 91A2 1577 3066 6110

   If you receive the following error message, confirm that you imported the correct public key:

   gpg: Can't check signature: public key not found

Configure the driver for your Maven application.

Copy the dependency snippet from the Maven Central Repository. Edit the version number in the dependency snippet to match your JDBC driver version.

For example:

<dependency>
   <groupId>org.mongodb</groupId>
   <artifactId>mongodb-jdbc</artifactId>
   <version>2.1.0</version>
</dependency>

Add the dependency to your Maven project.

In the pom.xml file for your project, paste the snippet into the dependencies list as follows:

<dependencies>
  <dependency>
      <groupId>org.mongodb</groupId>
      <artifactId>mongodb-jdbc</artifactId>
      <version>2.1.0</version>
  </dependency>
</dependencies>

Connect to your federated database instance.

To connect to your federated database instance, create a connection string and open a connection from your application. The connection string for the JDBC driver follows the format of the standard MongoDB connection string, except with the jdbc: prefix:

jdbc:mongodb://[username:password]@[host].a.query.mongodb.net/<databaseName>[?option1=value1[&option2=value2]...]

To get the connection string from the Atlas UI, do the following:

1. In the Atlas UI, go to the Data Federation page and click Connect for the federated database instance that you want to connect to.

2. Under Access your data through tools, select Atlas SQL.

3. Under Select your driver, select JDBC Driver from the dropdown.

4. Under Get Connection String, select the database that you want to connect to and copy the connection string.

The following example demonstrates how to open a connection. In addition to the connection string, you must also specify the database to use through a Properties object parameter. To learn more, see Connection Strings and Connection Properties.

java.util.Properties p = new java.util.Properties();
p.setProperty("database", "<databaseName>");
Connection conn = DriverManager.getConnection("<connectionString>", p);