> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # SQL Interface Driver Setup This page describes how to install and configure the MongoDB JDBC (Java Database Connectivity) or ODBC (Open Database Connectivity) drivers for connecting your BI (Business Intelligence) tool to your Atlas or self-managed [Enterprise Advanced (EA)](http://www.mongodb.com/products/self-managed/enterprise-advanced?tck=docs) database. Reference the table below to find the correct driver for your BI (Business Intelligence) tool. | Driver | BI Tool | | --- | --- | | **JDBC Driver** | [Tableau](https://www.tableau.com/) Desktop, Server, or Cloud or other JDBC-supported tools such as DBeaver, DataGrip, or a Maven project. | | **ODBC Driver** | [Power BI Desktop](https://learn.microsoft.com/en-us/power-bi/fundamentals/desktop-get-the-desktop/) or other ODBC-supported tools such as Excel. | **Note:** MongoDB officially supports [Tableau](https://www.tableau.com/) (Desktop, Server, or Cloud) and [Power BI Desktop](https://learn.microsoft.com/en-us/power-bi/fundamentals/desktop-get-the-desktop/) (Desktop and Service) with its JDBC (Java Database Connectivity) and ODBC (Open Database Connectivity) drivers. You can use the JDBC (Java Database Connectivity) and ODBC (Open Database Connectivity) drivers with other SQL-92 compatible tools, but MongoDB cannot guarantee compatibility. Test your specific SQL Interface features to confirm support. Choose your deployment type to get started: ## Prerequisites - A database user with the `read` privilege on the `__mdb_internal_sqlinterface` database. ## Install the JDBC Driver The MongoDB JDBC (Java Database Connectivity) driver is required for connecting to your database with Tableau, DBeaver, DataGrip, and other Java applications that accept a JDBC (Java Database Connectivity) API, such as a [Maven](https://maven.apache.org/) project. ### JDBC Driver Compatibility - The MongoDB JDBC (Java Database Connectivity) driver is compatible with: - Windows x86\_64 - macOS x86\_64 and macOS aarch64 architectures - linux x86\_64 and linux arm64 architectures - OpenSSL 3.0 or greater is required for secure connections. - You can authenticate with [SCRAM-SHA-1, SCRAM-SHA-256](https://www.mongodb.com/docs/manual/core/security-scram.md#std-label-authentication-scram), [X.509](https://www.mongodb.com/docs/manual/core/security-x.509.md#std-label-security-auth-x509), [LDAP](https://www.mongodb.com/docs/manual/core/security-ldap.md#std-label-security-ldap), [Kerberos (GSSAPI)](https://www.mongodb.com/docs/manual/core/kerberos.md#std-label-security-kerberos), [OpenID Connect](https://www.mongodb.com/docs/manual/core/oidc/security-oidc.md#std-label-authentication-oidc), and [MongoDB Passwordless Authentication with AWS](https://www.mongodb.com/docs/atlas/security/aws-iam-authentication.md#std-label-set-up-pwdless-auth). To configure X.509, Kerberos, or OIDC (OpenID Connect) for the JDBC (Java Database Connectivity) driver, see [JDBC Driver Configuration.](https://www.mongodb.com/docs/sql-interface/authentication.md#std-label-sql-auth-jdbc-config) **Note:** Not every authentication mechanism is supported depending on your deployment type. For the mechanisms that each component and deployment type supports, see [SQL Interface Authentication.](https://www.mongodb.com/docs/sql-interface/authentication.md#std-label-sql-authentication) ### Procedure 1. Download the MongoDB JDBC driver. Download the latest JDBC (Java Database Connectivity) driver from the [MongoDB download center.](https://www.mongodb.com/try/download/jdbc-driver/) **Note:** The JDBC (Java Database Connectivity) driver is available in two `jar` formats: - `mongodb-jdbc--all.jar` contains the driver and all necessary dependencies. Required for Tableau and DBeaver. - `mongodb-jdbc-.jar` contains the driver without bundled dependencies. Required for JetBrains tools. 2. Move the `jar` file to the appropriate directory for your operating system. Copy the `jar` file to the appropriate directory for your BI (Business Intelligence) tool. For example, if you're installing the JDBC (Java Database Connectivity) driver for Tableau: - **Windows:** `C:\Program Files\Tableau\Drivers` - **macOS:** `~/Library/Tableau/Drivers` - **Linux:** `/opt/tableau/tableau_driver/jdbc` 3. 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. Run the following command to download the `.asc` file from the [Maven Central Repository](https://search.maven.org/artifact/org.mongodb/mongodb-jdbc). Replace `` with the version of the driver you downloaded and `` with the name of the file you downloaded. ```sh curl -O https://repo1.maven.org/maven2/org/mongodb/mongodb-jdbc//.asc ``` For example, if you downloaded `mongodb-jdbc-2.2.3-all.jar`, you would run the following command. ```sh curl -O https://repo1.maven.org/maven2/org/mongodb/mongodb-jdbc/2.2.3/mongodb-jdbc-2.2.3-all.jar.asc ``` Run the following command to download, then import the key file. Replace `` with one of the current GPG key servers supported by Maven: - `keyserver.ubuntu.com` - `keys.openpgp.org` - `pgp.mit.edu` ```shell gpg --keyserver --recv-keys BDDC8671F1BE6F4D5464096624A4A8409351E954 ``` **Output:** ```shell gpg: key BDDC8671F1BE6F4D5464096624A4A8409351E954: public key "MongoDB JDBC Driver Release Signing Key " imported gpg: Total number processed: 1 gpg: imported: 1 ``` Run the following command to verify the MongoDB JDBC (Java Database Connectivity) driver installation file. Replace `` and `` with the names of the files you downloaded. ```text gpg --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. ```text 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: ```shell 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 " ``` If the package is properly signed, but you don't yet trust the signing key in your local `trustdb`, `gpg` also returns the following message: ```shell 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: ```shell gpg: Can't check signature: public key not found ``` ### Integrate with a Maven Project You can connect the MongoDB JDBC (Java Database Connectivity) driver with your Maven application. 1. Configure the driver for your Maven application. Copy the dependency snippet from the [Maven Central Repository](https://central.sonatype.com/artifact/org.mongodb/mongodb-jdbc). Edit the version number in the dependency snippet to match your JDBC driver version. For example: ```xml org.mongodb mongodb-jdbc 2.1.0 ``` 2. Add the dependency to your Maven project. In the `pom.xml` file for your project, paste the snippet into the dependencies list as follows: ```xml org.mongodb mongodb-jdbc 2.1.0 ``` ### Connect with the JDBC Driver After you install the JDBC (Java Database Connectivity) driver, connect to your database from your Java application. 1. Connect to your cluster. To connect to your dedicated cluster, create a connection string and open a connection from your application. The connection string for the JDBC (Java Database Connectivity) driver follows the format of the standard MongoDB connection URI (Uniform Resource Identifier), except with the `jdbc:` prefix: `jdbc:`. ```text jdbc:mongodb+srv:///?ssl=true&authSource=admin ``` To get the connection string from the Atlas UI, do the following: In the Atlas UI, go to the Clusters page and click Connect for the cluster that you want to connect to. Under Access your data through tools, select Atlas SQL. Under Select your driver, select JDBC Driver from the dropdown. Under Get Connection String, select the database that you want to connect to and copy the connection string. You must enable the SQL Interface for the cluster before you can connect. To learn more, see [Connect Your SQL Tool to MongoDB.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-sql-connect) 2. Configure logging for the JDBC (Java Database Connectivity) driver. You set logging options the same way that you set other database properties. To configure logging, set the following properties: ```properties loglevel=INFO logdir= ``` The `loglevel` property sets the verbosity of the driver logs. It accepts the following values, in order of increasing verbosity: `OFF`, `SEVERE`, `WARNING`, `INFO`, `FINE`, and `FINER`. The default is `OFF`. The `logdir` property sets the directory where the driver writes log files. The directory must already exist. If you omit `logdir` or set it to `console`, the driver writes logs to the console instead of to a file. **Important:** In production environments, start with the `SEVERE` log level. Raise the level only when you must diagnose an issue, because each level adds a large amount of output. At the `FINER` level, the driver logs every call that retrieves data for each cell of each result set. If you connect from Tableau, set these properties in the `mongodb_jdbc.properties` file. To learn more, see [Configure Tableau Logging.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-sql-connect-tableau-logging) 3. Open a connection from your application. 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](https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-connection-options) and [Connection Properties.](https://github.com//mongodb/mongo-jdbc-driver#connection-properties) ```java java.util.Properties p = new java.util.Properties(); p.setProperty("database", ""); p.setProperty("loglevel", "debug"); p.setProperty("logdir", "your/path"); Connection conn = DriverManager.getConnection("", p); ``` **Note:** Any special characters in the connection string for the JDBC (Java Database Connectivity) driver must be URL encoded. ## Install the ODBC Driver The MongoDB ODBC (Open Database Connectivity) driver is required for connecting to your database with Power BI, Excel, or other ODBC-supported BI (Business Intelligence) tools. ### ODBC Driver Compatibility - The MongoDB ODBC (Open Database Connectivity) driver is compatible with: - Windows - Linux glibc 2.34+ (x86\_64 and arm64) - You can authenticate with [SCRAM-SHA-1, SCRAM-SHA-256](https://www.mongodb.com/docs/manual/core/security-scram/), [X.509](https://www.mongodb.com/docs/manual/core/security-x.509.md#std-label-security-auth-x509), and, where applicable, [MongoDB Passwordless Authentication with AWS.](https://www.mongodb.com/docs/atlas/security/aws-iam-authentication.md#std-label-set-up-pwdless-auth) ### Prerequisites ### Windows - [Microsoft Visual C++ Redistributable 17.0](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170) or higher for installing Microsoft C and C++ (MSVC) runtime libraries. **Note:** If the C++ runtime libraries are not installed, the ODBC (Open Database Connectivity) driver returns the following error: ```sh The specified module could not be found (path of the dll which exists and has the proper permission). ``` ### Procedure ### Windows 1. Download the MongoDB ODBC driver. Download the latest ODBC (Open Database Connectivity) driver from the [MongoDB download center.](https://www.mongodb.com/try/download/odbc-driver/) 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. Complete the following steps to verify the ODBC driver binary against its SHA256 key: On the [MongoDB download center](https://www.mongodb.com/try/download/odbc-driver/), click Copy link for the Windows installer. Append `.sha256` to the copied URL and download the result. MongoDB publishes the checksum file alongside each installer, so this URL is correct for every release. Compare the checksum file to the MongoDB installer hash using the following PowerShell script. Replace `` with the name of the installer you downloaded, without the `.msi` extension: ```shell $sigHash = (Get-Content $Env:HomePath\Downloads\.msi.sha256 | Out-String).SubString(0,64).ToUpper(); ` $fileHash = (Get-FileHash $Env:HomePath\Downloads\.msi).Hash.Trim(); ` echo $sigHash; echo $fileHash; ` $sigHash -eq $fileHash ``` The command outputs three lines: - A SHA256 hash that you downloaded directly from MongoDB. - A SHA256 hash computed from the MongoDB ODBC driver binary you downloaded from MongoDB. - A True or False result depending if the hashes match. If the hashes match, the MongoDB binary is verified. 3. Install the ODBC driver. Run the installation file that you downloaded to open the Atlas SQL ODBC Setup Wizard. Follow the steps in the Setup Wizard. 4. Configure a System DSN. **Note:** You don't need to configure a DSN to connect from Power BI Desktop with the Power BI Connector for MongoDB, in either Import Mode or Direct Query. To learn more, see [Connect Power BI.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-connect-powerbi) To configure your ODBC (Open Database Connectivity) connection: Open your ODBC Data Source Administrator. **Note:** If you use a 64-bit processor, be sure to open the 64-bit ODBC Data Source Administrator. Navigate to the **System DSN** tab. Add a new **System DSN**. When prompted to select a driver for your data source, select the MongoDB Atlas SQL ODBC Driver. Enter your connection information. You must enter: **Note:** For an Atlas dedicated cluster or federated database instance, get your connection information from the Atlas UI: click Connect, then select Atlas SQL Interface. For a self-managed [Enterprise Advanced (EA)](http://www.mongodb.com/products/self-managed/enterprise-advanced?tck=docs) deployment, use your MongoDB deployment URI (Uniform Resource Identifier). To learn more, see [Connect Your SQL Tool to MongoDB.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-sql-connect) | Field | Description | | --- | --- | | DSN | A name for your new DSN. | | Username | A database username to use to connect to your database. | | Password | The database user's password. | | MongoDB URI | Your MongoDB deployment URI. | | Database | The name of the database to which to connect. | | Enable maximum | Checkbox to enforce maximum string length of 4000 characters. You must enable this option to work with BI (Business Intelligence) tools like Microsoft SQL Server Management Studio that can't support variable length string data with unknown maximum length. | Once you enter the required connection information, you can test your connection with your ODBC Data Source Administrator. 5. Configure logging for the ODBC driver. Enable SQL trace logging within the ODBC (Open Database Connectivity) driver either by setting it in the connection string or by adding a key value pair to the Windows System registry. You can configure the ODBC (Open Database Connectivity) driver log level by adding a key-value pair to the Windows System registry, either directly or by using a `.ini` file. To learn more, see the [Windows documentation on configuring the system registry.](https://learn.microsoft.com/en-us/windows/win32/sysinfo/registry) If you set in both the driver and the connection string, the connection string setting takes precedence. You can specify the desired log level. Logs are hierarchical, which means MongoSQL logs all messages at or above the level you set. You can configure one of the following log levels: - `error` - to log only error messages - `warn` - to log all warnings - `info` - to log messages of info, errors, and warnings - `debug` - to log all messages of error and info - `trace` - to log all trace messages - `off` - to disable logging `info` excludes debug and trace messages. `debug` messages don't appear in the logs. The default log level is `info`. You can change the log level by appending the key `loglevel` and value to your ODBC connection string. **Example:** The following changes the log level to `debug`: ```text loglevel=debug ``` The following changes the log level to `error`: ```text loglevel=error ``` By default, MongoSQL writes logs to a file named `mongo_odbc.log` that it creates in the `logs` folder. MongoSQL writes logs to the file in the following path: ```text C:\Users\Documents\MongoDB\Atlas SQL ODBC\logs\mongo_odbc.log ``` MongoSQL automatically rotates the logs when the file size reaches `.5MB`. The log files are named `mongo_odbc.log.x` where the `x` denotes the number of rotation. MongoSQL only keeps up to 10 log files. When there are 10 log files, MongoSQL automatically rotates and shuffles such that `mongo_odbc.log.1` becomes `mongo_odbc.log.2` and so on. ## Install the JDBC Driver The MongoDB JDBC (Java Database Connectivity) driver is required for connecting to your database with Tableau, DBeaver, DataGrip, and other Java applications that accept a JDBC (Java Database Connectivity) API, such as a [Maven](https://maven.apache.org/) project. ### JDBC Driver Compatibility - The MongoDB JDBC (Java Database Connectivity) driver is compatible with: - Windows x86\_64 - macOS x86\_64 and macOS aarch64 architectures - linux x86\_64 and linux arm64 architectures - OpenSSL 3.0 or greater is required for secure connections. - You can authenticate with [SCRAM-SHA-1, SCRAM-SHA-256](https://www.mongodb.com/docs/manual/core/security-scram.md#std-label-authentication-scram), [X.509](https://www.mongodb.com/docs/manual/core/security-x.509.md#std-label-security-auth-x509), [LDAP](https://www.mongodb.com/docs/manual/core/security-ldap.md#std-label-security-ldap), [Kerberos (GSSAPI)](https://www.mongodb.com/docs/manual/core/kerberos.md#std-label-security-kerberos), [OpenID Connect](https://www.mongodb.com/docs/manual/core/oidc/security-oidc.md#std-label-authentication-oidc), and [MongoDB Passwordless Authentication with AWS](https://www.mongodb.com/docs/atlas/security/aws-iam-authentication.md#std-label-set-up-pwdless-auth). To configure X.509, Kerberos, or OIDC (OpenID Connect) for the JDBC (Java Database Connectivity) driver, see [JDBC Driver Configuration.](https://www.mongodb.com/docs/sql-interface/authentication.md#std-label-sql-auth-jdbc-config) **Note:** Not every authentication mechanism is supported depending on your deployment type. For the mechanisms that each component and deployment type supports, see [SQL Interface Authentication.](https://www.mongodb.com/docs/sql-interface/authentication.md#std-label-sql-authentication) ### Procedure 1. Download the MongoDB JDBC driver. Download the latest JDBC (Java Database Connectivity) driver from the [MongoDB download center.](https://www.mongodb.com/try/download/jdbc-driver/) **Note:** The JDBC (Java Database Connectivity) driver is available in two `jar` formats: - `mongodb-jdbc--all.jar` contains the driver and all necessary dependencies. Required for Tableau and DBeaver. - `mongodb-jdbc-.jar` contains the driver without bundled dependencies. Required for JetBrains tools. 2. Move the `jar` file to the appropriate directory for your operating system. Copy the `jar` file to the appropriate directory for your BI (Business Intelligence) tool. For example, if you're installing the JDBC (Java Database Connectivity) driver for Tableau: - **Windows:** `C:\Program Files\Tableau\Drivers` - **macOS:** `~/Library/Tableau/Drivers` - **Linux:** `/opt/tableau/tableau_driver/jdbc` 3. 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. Run the following command to download the `.asc` file from the [Maven Central Repository](https://search.maven.org/artifact/org.mongodb/mongodb-jdbc). Replace `` with the version of the driver you downloaded and `` with the name of the file you downloaded. ```sh curl -O https://repo1.maven.org/maven2/org/mongodb/mongodb-jdbc//.asc ``` For example, if you downloaded `mongodb-jdbc-2.2.3-all.jar`, you would run the following command. ```sh curl -O https://repo1.maven.org/maven2/org/mongodb/mongodb-jdbc/2.2.3/mongodb-jdbc-2.2.3-all.jar.asc ``` Run the following command to download, then import the key file. Replace `` with one of the current GPG key servers supported by Maven: - `keyserver.ubuntu.com` - `keys.openpgp.org` - `pgp.mit.edu` ```shell gpg --keyserver --recv-keys BDDC8671F1BE6F4D5464096624A4A8409351E954 ``` **Output:** ```shell gpg: key BDDC8671F1BE6F4D5464096624A4A8409351E954: public key "MongoDB JDBC Driver Release Signing Key " imported gpg: Total number processed: 1 gpg: imported: 1 ``` Run the following command to verify the MongoDB JDBC (Java Database Connectivity) driver installation file. Replace `` and `` with the names of the files you downloaded. ```text gpg --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. ```text 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: ```shell 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 " ``` If the package is properly signed, but you don't yet trust the signing key in your local `trustdb`, `gpg` also returns the following message: ```shell 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: ```shell gpg: Can't check signature: public key not found ``` ### Integrate with a Maven Project You can connect the MongoDB JDBC (Java Database Connectivity) driver with your Maven application. 1. Configure the driver for your Maven application. Copy the dependency snippet from the [Maven Central Repository](https://central.sonatype.com/artifact/org.mongodb/mongodb-jdbc). Edit the version number in the dependency snippet to match your JDBC driver version. For example: ```xml org.mongodb mongodb-jdbc 2.1.0 ``` 2. Add the dependency to your Maven project. In the `pom.xml` file for your project, paste the snippet into the dependencies list as follows: ```xml org.mongodb mongodb-jdbc 2.1.0 ``` ### Connect with the JDBC Driver After you install the JDBC (Java Database Connectivity) driver, connect to your database from your Java application. 1. 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 (Java Database Connectivity) driver follows the format of the standard MongoDB connection URI (Uniform Resource Identifier), except with the `jdbc:` prefix: `jdbc:`. ```text jdbc:mongodb://[username:password]@[host].a.query.mongodb.net/[?option1=value1[&option2=value2]...] ``` To get the connection string from the Atlas UI, do the following: In the Atlas UI, go to the Data Federation page and click Connect for the federated database instance that you want to connect to. Under Access your data through tools, select Atlas SQL. Under Select your driver, select JDBC Driver from the dropdown. Under Get Connection String, select the database that you want to connect to and copy the connection string. 2. Configure logging for the JDBC (Java Database Connectivity) driver. You set logging options the same way that you set other database properties. To configure logging, set the following properties: ```properties loglevel=INFO logdir= ``` The `loglevel` property sets the verbosity of the driver logs. It accepts the following values, in order of increasing verbosity: `OFF`, `SEVERE`, `WARNING`, `INFO`, `FINE`, and `FINER`. The default is `OFF`. The `logdir` property sets the directory where the driver writes log files. The directory must already exist. If you omit `logdir` or set it to `console`, the driver writes logs to the console instead of to a file. **Important:** In production environments, start with the `SEVERE` log level. Raise the level only when you must diagnose an issue, because each level adds a large amount of output. At the `FINER` level, the driver logs every call that retrieves data for each cell of each result set. If you connect from Tableau, set these properties in the `mongodb_jdbc.properties` file. To learn more, see [Configure Tableau Logging.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-sql-connect-tableau-logging) 3. Open a connection from your application. 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](https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-connection-options) and [Connection Properties.](https://github.com//mongodb/mongo-jdbc-driver#connection-properties) ```java java.util.Properties p = new java.util.Properties(); p.setProperty("database", ""); p.setProperty("loglevel", "debug"); p.setProperty("logdir", "your/path"); Connection conn = DriverManager.getConnection("", p); ``` **Note:** Any special characters in the connection string for the JDBC (Java Database Connectivity) driver must be URL encoded. ## Install the ODBC Driver The MongoDB ODBC (Open Database Connectivity) driver is required for connecting to your database with Power BI, Excel, or other ODBC-supported BI (Business Intelligence) tools. ### ODBC Driver Compatibility - The MongoDB ODBC (Open Database Connectivity) driver is compatible with: - Windows - Linux glibc 2.34+ (x86\_64 and arm64) - You can authenticate with [SCRAM-SHA-1, SCRAM-SHA-256](https://www.mongodb.com/docs/manual/core/security-scram/), [X.509](https://www.mongodb.com/docs/manual/core/security-x.509.md#std-label-security-auth-x509), and, where applicable, [MongoDB Passwordless Authentication with AWS.](https://www.mongodb.com/docs/atlas/security/aws-iam-authentication.md#std-label-set-up-pwdless-auth) ### Prerequisites ### Windows - [Microsoft Visual C++ Redistributable 17.0](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170) or higher for installing Microsoft C and C++ (MSVC) runtime libraries. **Note:** If the C++ runtime libraries are not installed, the ODBC (Open Database Connectivity) driver returns the following error: ```sh The specified module could not be found (path of the dll which exists and has the proper permission). ``` ### Procedure ### Windows 1. Download the MongoDB ODBC driver. Download the latest ODBC (Open Database Connectivity) driver from the [MongoDB download center.](https://www.mongodb.com/try/download/odbc-driver/) 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. Complete the following steps to verify the ODBC driver binary against its SHA256 key: On the [MongoDB download center](https://www.mongodb.com/try/download/odbc-driver/), click Copy link for the Windows installer. Append `.sha256` to the copied URL and download the result. MongoDB publishes the checksum file alongside each installer, so this URL is correct for every release. Compare the checksum file to the MongoDB installer hash using the following PowerShell script. Replace `` with the name of the installer you downloaded, without the `.msi` extension: ```shell $sigHash = (Get-Content $Env:HomePath\Downloads\.msi.sha256 | Out-String).SubString(0,64).ToUpper(); ` $fileHash = (Get-FileHash $Env:HomePath\Downloads\.msi).Hash.Trim(); ` echo $sigHash; echo $fileHash; ` $sigHash -eq $fileHash ``` The command outputs three lines: - A SHA256 hash that you downloaded directly from MongoDB. - A SHA256 hash computed from the MongoDB ODBC driver binary you downloaded from MongoDB. - A True or False result depending if the hashes match. If the hashes match, the MongoDB binary is verified. 3. Install the ODBC driver. Run the installation file that you downloaded to open the Atlas SQL ODBC Setup Wizard. Follow the steps in the Setup Wizard. 4. Configure a System DSN. **Note:** You don't need to configure a DSN to connect from Power BI Desktop with the Power BI Connector for MongoDB, in either Import Mode or Direct Query. To learn more, see [Connect Power BI.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-connect-powerbi) To configure your ODBC (Open Database Connectivity) connection: Open your ODBC Data Source Administrator. **Note:** If you use a 64-bit processor, be sure to open the 64-bit ODBC Data Source Administrator. Navigate to the **System DSN** tab. Add a new **System DSN**. When prompted to select a driver for your data source, select the MongoDB Atlas SQL ODBC Driver. Enter your connection information. You must enter: **Note:** For an Atlas dedicated cluster or federated database instance, get your connection information from the Atlas UI: click Connect, then select Atlas SQL Interface. For a self-managed [Enterprise Advanced (EA)](http://www.mongodb.com/products/self-managed/enterprise-advanced?tck=docs) deployment, use your MongoDB deployment URI (Uniform Resource Identifier). To learn more, see [Connect Your SQL Tool to MongoDB.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-sql-connect) | Field | Description | | --- | --- | | DSN | A name for your new DSN. | | Username | A database username to use to connect to your database. | | Password | The database user's password. | | MongoDB URI | Your MongoDB deployment URI. | | Database | The name of the database to which to connect. | | Enable maximum | Checkbox to enforce maximum string length of 4000 characters. You must enable this option to work with BI (Business Intelligence) tools like Microsoft SQL Server Management Studio that can't support variable length string data with unknown maximum length. | Once you enter the required connection information, you can test your connection with your ODBC Data Source Administrator. 5. Configure logging for the ODBC driver. Enable SQL trace logging within the ODBC (Open Database Connectivity) driver either by setting it in the connection string or by adding a key value pair to the Windows System registry. You can configure the ODBC (Open Database Connectivity) driver log level by adding a key-value pair to the Windows System registry, either directly or by using a `.ini` file. To learn more, see the [Windows documentation on configuring the system registry.](https://learn.microsoft.com/en-us/windows/win32/sysinfo/registry) If you set in both the driver and the connection string, the connection string setting takes precedence. You can specify the desired log level. Logs are hierarchical, which means MongoSQL logs all messages at or above the level you set. You can configure one of the following log levels: - `error` - to log only error messages - `warn` - to log all warnings - `info` - to log messages of info, errors, and warnings - `debug` - to log all messages of error and info - `trace` - to log all trace messages - `off` - to disable logging `info` excludes debug and trace messages. `debug` messages don't appear in the logs. The default log level is `info`. You can change the log level by appending the key `loglevel` and value to your ODBC connection string. **Example:** The following changes the log level to `debug`: ```text loglevel=debug ``` The following changes the log level to `error`: ```text loglevel=error ``` By default, MongoSQL writes logs to a file named `mongo_odbc.log` that it creates in the `logs` folder. MongoSQL writes logs to the file in the following path: ```text C:\Users\Documents\MongoDB\Atlas SQL ODBC\logs\mongo_odbc.log ``` MongoSQL automatically rotates the logs when the file size reaches `.5MB`. The log files are named `mongo_odbc.log.x` where the `x` denotes the number of rotation. MongoSQL only keeps up to 10 log files. When there are 10 log files, MongoSQL automatically rotates and shuffles such that `mongo_odbc.log.1` becomes `mongo_odbc.log.2` and so on. ## Install the JDBC Driver The MongoDB JDBC (Java Database Connectivity) driver is required for connecting to your database with Tableau, DBeaver, DataGrip, and other Java applications that accept a JDBC (Java Database Connectivity) API, such as a [Maven](https://maven.apache.org/) project. ### JDBC Driver Compatibility - The MongoDB JDBC (Java Database Connectivity) driver is compatible with: - Windows x86\_64 - macOS x86\_64 and macOS aarch64 architectures - linux x86\_64 and linux arm64 architectures - OpenSSL 3.0 or greater is required for secure connections. - You can authenticate with [SCRAM-SHA-1, SCRAM-SHA-256](https://www.mongodb.com/docs/manual/core/security-scram.md#std-label-authentication-scram), [X.509](https://www.mongodb.com/docs/manual/core/security-x.509.md#std-label-security-auth-x509), [LDAP](https://www.mongodb.com/docs/manual/core/security-ldap.md#std-label-security-ldap), [Kerberos (GSSAPI)](https://www.mongodb.com/docs/manual/core/kerberos.md#std-label-security-kerberos), [OpenID Connect](https://www.mongodb.com/docs/manual/core/oidc/security-oidc.md#std-label-authentication-oidc), and [MongoDB Passwordless Authentication with AWS](https://www.mongodb.com/docs/atlas/security/aws-iam-authentication.md#std-label-set-up-pwdless-auth). To configure X.509, Kerberos, or OIDC (OpenID Connect) for the JDBC (Java Database Connectivity) driver, see [JDBC Driver Configuration.](https://www.mongodb.com/docs/sql-interface/authentication.md#std-label-sql-auth-jdbc-config) **Note:** Not every authentication mechanism is supported depending on your deployment type. For the mechanisms that each component and deployment type supports, see [SQL Interface Authentication.](https://www.mongodb.com/docs/sql-interface/authentication.md#std-label-sql-authentication) ### Procedure 1. Download the MongoDB JDBC driver. Download the latest JDBC (Java Database Connectivity) driver from the [MongoDB download center.](https://www.mongodb.com/try/download/jdbc-driver/) **Note:** The JDBC (Java Database Connectivity) driver is available in two `jar` formats: - `mongodb-jdbc--all.jar` contains the driver and all necessary dependencies. Required for Tableau and DBeaver. - `mongodb-jdbc-.jar` contains the driver without bundled dependencies. Required for JetBrains tools. 2. Move the `jar` file to the appropriate directory for your operating system. Copy the `jar` file to the appropriate directory for your BI (Business Intelligence) tool. For example, if you're installing the JDBC (Java Database Connectivity) driver for Tableau: - **Windows:** `C:\Program Files\Tableau\Drivers` - **macOS:** `~/Library/Tableau/Drivers` - **Linux:** `/opt/tableau/tableau_driver/jdbc` 3. 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. Run the following command to download the `.asc` file from the [Maven Central Repository](https://search.maven.org/artifact/org.mongodb/mongodb-jdbc). Replace `` with the version of the driver you downloaded and `` with the name of the file you downloaded. ```sh curl -O https://repo1.maven.org/maven2/org/mongodb/mongodb-jdbc//.asc ``` For example, if you downloaded `mongodb-jdbc-2.2.3-all.jar`, you would run the following command. ```sh curl -O https://repo1.maven.org/maven2/org/mongodb/mongodb-jdbc/2.2.3/mongodb-jdbc-2.2.3-all.jar.asc ``` Run the following command to download, then import the key file. Replace `` with one of the current GPG key servers supported by Maven: - `keyserver.ubuntu.com` - `keys.openpgp.org` - `pgp.mit.edu` ```shell gpg --keyserver --recv-keys BDDC8671F1BE6F4D5464096624A4A8409351E954 ``` **Output:** ```shell gpg: key BDDC8671F1BE6F4D5464096624A4A8409351E954: public key "MongoDB JDBC Driver Release Signing Key " imported gpg: Total number processed: 1 gpg: imported: 1 ``` Run the following command to verify the MongoDB JDBC (Java Database Connectivity) driver installation file. Replace `` and `` with the names of the files you downloaded. ```text gpg --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. ```text 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: ```shell 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 " ``` If the package is properly signed, but you don't yet trust the signing key in your local `trustdb`, `gpg` also returns the following message: ```shell 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: ```shell gpg: Can't check signature: public key not found ``` ### Integrate with a Maven Project You can connect the MongoDB JDBC (Java Database Connectivity) driver with your Maven application. 1. Configure the driver for your Maven application. Copy the dependency snippet from the [Maven Central Repository](https://central.sonatype.com/artifact/org.mongodb/mongodb-jdbc). Edit the version number in the dependency snippet to match your JDBC driver version. For example: ```xml org.mongodb mongodb-jdbc 2.1.0 ``` 2. Add the dependency to your Maven project. In the `pom.xml` file for your project, paste the snippet into the dependencies list as follows: ```xml org.mongodb mongodb-jdbc 2.1.0 ``` ### Connect with the JDBC Driver After you install the JDBC (Java Database Connectivity) driver, connect to your database from your Java application. 1. Connect to your deployment. To connect to your self-managed deployment, create a connection string and open a connection from your application. The connection string for the JDBC (Java Database Connectivity) driver follows the format of the standard MongoDB connection URI (Uniform Resource Identifier), except with the `jdbc:` prefix: `jdbc:`. ```text jdbc:mongodb://[username:password@][:port][/databaseName][?option1=value1[&option2=value2]...] ``` 2. Configure logging for the JDBC (Java Database Connectivity) driver. You set logging options the same way that you set other database properties. To configure logging, set the following properties: ```properties loglevel=INFO logdir= ``` The `loglevel` property sets the verbosity of the driver logs. It accepts the following values, in order of increasing verbosity: `OFF`, `SEVERE`, `WARNING`, `INFO`, `FINE`, and `FINER`. The default is `OFF`. The `logdir` property sets the directory where the driver writes log files. The directory must already exist. If you omit `logdir` or set it to `console`, the driver writes logs to the console instead of to a file. **Important:** In production environments, start with the `SEVERE` log level. Raise the level only when you must diagnose an issue, because each level adds a large amount of output. At the `FINER` level, the driver logs every call that retrieves data for each cell of each result set. If you connect from Tableau, set these properties in the `mongodb_jdbc.properties` file. To learn more, see [Configure Tableau Logging.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-sql-connect-tableau-logging) 3. Open a connection from your application. 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](https://www.mongodb.com/docs/manual/reference/connection-string/#std-label-connections-connection-options) and [Connection Properties.](https://github.com//mongodb/mongo-jdbc-driver#connection-properties) ```java java.util.Properties p = new java.util.Properties(); p.setProperty("database", ""); p.setProperty("loglevel", "debug"); p.setProperty("logdir", "your/path"); Connection conn = DriverManager.getConnection("", p); ``` **Note:** Any special characters in the connection string for the JDBC (Java Database Connectivity) driver must be URL encoded. ## Install the ODBC Driver The MongoDB ODBC (Open Database Connectivity) driver is required for connecting to your database with Power BI, Excel, or other ODBC-supported BI (Business Intelligence) tools. ### ODBC Driver Compatibility - The MongoDB ODBC (Open Database Connectivity) driver is compatible with: - Windows - Linux glibc 2.34+ (x86\_64 and arm64) - You can authenticate with [SCRAM-SHA-1, SCRAM-SHA-256](https://www.mongodb.com/docs/manual/core/security-scram/), [X.509](https://www.mongodb.com/docs/manual/core/security-x.509.md#std-label-security-auth-x509), and, where applicable, [MongoDB Passwordless Authentication with AWS.](https://www.mongodb.com/docs/atlas/security/aws-iam-authentication.md#std-label-set-up-pwdless-auth) ### Prerequisites ### Windows - [Microsoft Visual C++ Redistributable 17.0](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170) or higher for installing Microsoft C and C++ (MSVC) runtime libraries. **Note:** If the C++ runtime libraries are not installed, the ODBC (Open Database Connectivity) driver returns the following error: ```sh The specified module could not be found (path of the dll which exists and has the proper permission). ``` ### Procedure ### Windows 1. Download the MongoDB ODBC driver. Download the latest ODBC (Open Database Connectivity) driver from the [MongoDB download center.](https://www.mongodb.com/try/download/odbc-driver/) 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. Complete the following steps to verify the ODBC driver binary against its SHA256 key: On the [MongoDB download center](https://www.mongodb.com/try/download/odbc-driver/), click Copy link for the Windows installer. Append `.sha256` to the copied URL and download the result. MongoDB publishes the checksum file alongside each installer, so this URL is correct for every release. Compare the checksum file to the MongoDB installer hash using the following PowerShell script. Replace `` with the name of the installer you downloaded, without the `.msi` extension: ```shell $sigHash = (Get-Content $Env:HomePath\Downloads\.msi.sha256 | Out-String).SubString(0,64).ToUpper(); ` $fileHash = (Get-FileHash $Env:HomePath\Downloads\.msi).Hash.Trim(); ` echo $sigHash; echo $fileHash; ` $sigHash -eq $fileHash ``` The command outputs three lines: - A SHA256 hash that you downloaded directly from MongoDB. - A SHA256 hash computed from the MongoDB ODBC driver binary you downloaded from MongoDB. - A True or False result depending if the hashes match. If the hashes match, the MongoDB binary is verified. 3. Install the ODBC driver. Run the installation file that you downloaded to open the Atlas SQL ODBC Setup Wizard. Follow the steps in the Setup Wizard. 4. Configure a System DSN. **Note:** You don't need to configure a DSN to connect from Power BI Desktop with the Power BI Connector for MongoDB, in either Import Mode or Direct Query. To learn more, see [Connect Power BI.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-connect-powerbi) To configure your ODBC (Open Database Connectivity) connection: Open your ODBC Data Source Administrator. **Note:** If you use a 64-bit processor, be sure to open the 64-bit ODBC Data Source Administrator. Navigate to the **System DSN** tab. Add a new **System DSN**. When prompted to select a driver for your data source, select the MongoDB Atlas SQL ODBC Driver. Enter your connection information. You must enter: **Note:** For an Atlas dedicated cluster or federated database instance, get your connection information from the Atlas UI: click Connect, then select Atlas SQL Interface. For a self-managed [Enterprise Advanced (EA)](http://www.mongodb.com/products/self-managed/enterprise-advanced?tck=docs) deployment, use your MongoDB deployment URI (Uniform Resource Identifier). To learn more, see [Connect Your SQL Tool to MongoDB.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-sql-connect) | Field | Description | | --- | --- | | DSN | A name for your new DSN. | | Username | A database username to use to connect to your database. | | Password | The database user's password. | | MongoDB URI | Your MongoDB deployment URI. | | Database | The name of the database to which to connect. | | Enable maximum | Checkbox to enforce maximum string length of 4000 characters. You must enable this option to work with BI (Business Intelligence) tools like Microsoft SQL Server Management Studio that can't support variable length string data with unknown maximum length. | Once you enter the required connection information, you can test your connection with your ODBC Data Source Administrator. 5. Configure logging for the ODBC driver. Enable SQL trace logging within the ODBC (Open Database Connectivity) driver either by setting it in the connection string or by adding a key value pair to the Windows System registry. You can configure the ODBC (Open Database Connectivity) driver log level by adding a key-value pair to the Windows System registry, either directly or by using a `.ini` file. To learn more, see the [Windows documentation on configuring the system registry.](https://learn.microsoft.com/en-us/windows/win32/sysinfo/registry) If you set in both the driver and the connection string, the connection string setting takes precedence. You can specify the desired log level. Logs are hierarchical, which means MongoSQL logs all messages at or above the level you set. You can configure one of the following log levels: - `error` - to log only error messages - `warn` - to log all warnings - `info` - to log messages of info, errors, and warnings - `debug` - to log all messages of error and info - `trace` - to log all trace messages - `off` - to disable logging `info` excludes debug and trace messages. `debug` messages don't appear in the logs. The default log level is `info`. You can change the log level by appending the key `loglevel` and value to your ODBC connection string. **Example:** The following changes the log level to `debug`: ```text loglevel=debug ``` The following changes the log level to `error`: ```text loglevel=error ``` By default, MongoSQL writes logs to a file named `mongo_odbc.log` that it creates in the `logs` folder. MongoSQL writes logs to the file in the following path: ```text C:\Users\Documents\MongoDB\Atlas SQL ODBC\logs\mongo_odbc.log ``` MongoSQL automatically rotates the logs when the file size reaches `.5MB`. The log files are named `mongo_odbc.log.x` where the `x` denotes the number of rotation. MongoSQL only keeps up to 10 log files. When there are 10 log files, MongoSQL automatically rotates and shuffles such that `mongo_odbc.log.1` becomes `mongo_odbc.log.2` and so on. ## Next Steps After you have installed the correct driver for your BI (Business Intelligence) tool, [connect your BI tool to your database.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-sql-connect)