Docs Menu
Docs Home
MongoDB Atlas
/ / /

Connect to and Query Data with Free SQL Tools

This tutorial guides you through connecting to a federated database instance with the free tools MongoDB JDBC Driver and DBeaver (Community Edition).

If you followed the Advanced Configuration guide, this tutorial also guides you through querying sample data.

Install the following client software to connect to and query your data with Atlas SQL.


DBeaver is a free, universal database tool. You can use it to explore your sample data in this tutorial. Download and install DBeaver (Community Edition).


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.

    curl -O
  2. Run the following command to download then import the key file. Replace {server_url} with one of the current GPG key servers supported by Maven:




    gpg --keyserver {server_url} --recv-keys 91A2157730666110
    gpg: key 91A2157730666110: public key "Huan Li <>" imported
    gpg: Total number processed: 1
    gpg: imported: 1
  3. Run the following command to verify the MongoDB JDBC Driver installation file.

    gpg --verify mongodb-jdbc-2.1.2.jar.asc mongodb-jdbc-2.1.2.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 91A2157730666110
    gpg: Good signature from "Huan Li <>"

    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

To connect to your federated database instance from DBeaver:

  1. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your project from the Projects menu in the navigation bar.

  3. In the sidebar, click Data Federation under the Services heading.



This tutorial uses the JDBC Driver to connect. See Connect Using the Atlas SQL Interface for alternative connection methods.


Atlas Data Federation provides a connection string to connect to your federated database instance. You'll need this in a later step.

  1. In DBeaver, click Database and select Driver Manager from the dropdown menu.

  2. Click New to open the Create new driver modal.

  3. In the Settings tab, enter the following information:

    Driver Name
    Class Name
  4. In the Libraries tab, click Add File and add your JDBC driver all.jar file.

    Click Find Class.

  5. Click OK. The Create new driver modal closes.

  1. In DBeaver, click Database and select New Database Connection from the dropdown menu to open the Connect to a database modal.

  2. From the list of databases, select the MongoDB database driver that you created in the previous step.


    If you don't see MongoDB, select the All category inside the modal.

    Click Next.

  3. In the Main tab, enter the following information:

    Your connection string from step 5.
    The MongoDB user to connect with.
    The MongoDB user's password.
  4. In the Driver properties tab, expand User Properties. Add the following key-value properties:

    The name of your virtual database.
    The MongoDB user to connect with. Not required if you entered a Username in the previous step.
    The MongoDB user's password. Not required if you entered a Password in the previous step.

In the Database Navigator, expand your MongoDB connection to verify that the federated database instance store mapped to your data is accessible.

To learn more about the different methods you can use to connect to a federated database instance, see Connect Using the Atlas SQL Interface.

To run Atlas SQL queries in DBeaver:


The DBeaver Database Navigator displays your virtual databases.

  1. Right-click the virtual database you want to query.

  2. Select SQL Editor.

  3. Select Open SQL console.

    A new SQL console window opens connected to the virtual database you selected.


If the query is successful, Atlas SQL displays the results in a table view below your query.

If you followed the Advanced Configuration guide using sample data, try running the following Atlas SQL queries against the sample data in your federated database instance.

Otherwise, you can modify these example queries for your namespaces.

FROM Sessions

Atlas SQL returns all documents from the Sessions collection.

FROM Users

Atlas SQL returns two documents from the Users collection.

FROM Users
WHERE name = 'Jon Snow'

Atlas SQL returns documents from the Users collection where the user's name is Jon Snow.

For an Atlas SQL command reference, see Atlas SQL Language Reference.


SQL Tutorials