For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.
Docs Menu
Docs Home
/ /
SQL Tutorials
Docs Home
/
Tools
/
SQL Interface
/
SQL Tutorials
Docs Home
/
Tools
/
SQL Interface
/
SQL Tutorials

Connect to and Query Data with Free SQL Tools

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

If you loaded sample data into your deployment, this tutorial also guides you through querying it.

Before you start, configure your deployment to accept SQL connections. To learn how, see SQL Interface Server Setup.

Install Client Software

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

1

Install DBeaver

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).

2

Install the JDBC Driver

  1. Download the latest MongoDB JDBC Driver version.

  2. 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 {version-number} with the version of the driver you downloaded and {artifact_to_verify} with the name of the file you downloaded.

      curl -O https://repo1.maven.org/maven2/org/mongodb/mongodb-jdbc/{version-number}/{artifact_to_verify}.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 {server_url} with one of the current GPG key servers supported by Maven:

      • keyserver.ubuntu.com

      • keys.openpgp.org

      • pgp.mit.edu

      gpg --keyserver {server_url} --recv-keys BDDC8671F1BE6F4D5464096624A4A8409351E954
      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 detached_signature_file and artifact_to_verify with the names of the files you downloaded.

      gpg --verify {detached_signature_file} {artifact_to_verify}

      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

Connect from DBeaver

Choose your deployment type to get your connection string and configure DBeaver:

To learn more about the different methods you can use to connect, see Connect Your SQL Tool to MongoDB.

Run MongoSQL Queries

To run MongoSQL queries in DBeaver:

1

Expand your MongoDB connection.

The DBeaver Database Navigator displays your virtual databases.

2

Open a SQL console.

  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.

3

Enter a SQL query in the console.

4

Click Execute SQL Statement to run your SQL query.

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

Example MongoSQL Queries

If you loaded sample data into your deployment, try running the following MongoSQL queries against it.

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

SELECT Statement

SELECT *
FROM Sessions

MongoSQL returns all documents from the Sessions collection.

LIMIT Statement

SELECT *
FROM Users
LIMIT 2

MongoSQL returns two documents from the Users collection.

WHERE Statement

SELECT *
FROM Users
WHERE name = 'Jon Snow'

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

For an MongoSQL command reference, see MongoSQL Language Reference.

Back
SQL Tutorials
Next
Authentication
Rate this page