Create a System DSN

Start the Microsoft ODBC Data Sources program.

Choose the program version (64-bit or 32-bit) which is appropriate for your system and ODBC driver version.

Select the System DSN tab.

Click the Add button.

Select a MongoDB BI Connector ODBC Driver from the list of available drivers.

Select either the MongoDB ODBC ANSI Driver or the MongoDB ODBC Unicode Driver, then click OK.

Fill in the necessary form fields.

Click the Details button to expose the lower half of the form.

The following form fields are required:

(Optional) If authentication is enabled, provide connection information.

The following fields are required when running with --auth enabled or when connecting to an BI Connector for Atlas instance.

grace?source=admin

grace?mechanism=PLAIN&source=$external

grace@EXAMPLE.COM?mechanism=GSSAPI&source=$external

(Optional) If TLS/SSL is enabled, fill in the TLS/SSL form fields.

Access the TLS/SSL form fields by clicking Details >>, then the SSL tab. The following parameters are available and may be required, depending on your TLS/SSL configuration:

Click the Test button to test the ODBC connection.

If the connection is successful, click OK to add the DSN. If the connection fails, check to make sure your MongoDB user is correctly authenticated for the database named in the connection.

Launch ODBC Manager.

Click System DSN, then click Add.

Select a MongoDB BI Connector ODBC Driver from the list of available drivers.

Select either the MongoDB ANSI ODBC driver or the MongoDB Unicode ODBC driver, then click OK.

Enter a Data Source Name (DSN).

Optionally enter a Description.

Add the necessary keywords.

1. Add a keyword value pair by clicking the Add button.

2. Modify the Keyword by double-clicking on it, entering the desired keyword, then pressing enter.

3. Modify the Value by double-clicking on it, entering the desired keyword, then pressing enter.

Using the procedure above, add the following keywords:

For the complete list of ODBC parameters, see Connector/ODBC Connection Parameters.

For example, your user DSN configuration should look similar to the following:

(Optional) If authentication is enabled, add the authentication keywords.

1. Add a keyword value pair by clicking the Add button.

2. Modify the Keyword by double-clicking on it, entering the desired keyword, then pressing enter.

3. Modify the Value by double-clicking on it, entering the desired keyword, then pressing enter.

Using the procedure above, add the following keywords:

grace?source=admin

grace?mechanism=PLAIN&source=$external

grace@EXAMPLE.COM?mechanism=GSSAPI&source=$external

For the complete list of ODBC parameters, see Connector/ODBC Connection Parameters.

For example, your user DSN configuration should look similar to the following:

(Optional) If TLS/SSL is enabled, add the TLS/SSL keywords.

1. Add a keyword value pair by clicking the Add button.

2. Modify the Keyword by double-clicking on it, entering the desired keyword, then pressing enter.

3. Modify the Value by double-clicking on it, entering the desired keyword, then pressing enter.

Using the procedure above, add the following keywords depending on your TLS/SSL configuration:

For the complete list of ODBC parameters, see Connector/ODBC Connection Parameters.

For example, your user DSN configuration should look similar to the following:

Click OK to finish creating the DSN.

Check the location of your .so files

The MongoDB BI Connector ODBC Driver files are named libmdbodbca.so and libmdbodbcw.so. After downloading the MongoDB BI Connector ODBC Driver, move them to your /usr/local/lib directory.

Create an odbc.ini file

The file /etc/odbc.ini defines your Data Source Names. Below is an example odbc.ini file which is configured to use the MongoDB BI Connector ODBC Driver with a DSN called MongoDBODBC. Replace all necessary placeholder values with values for your system.

The file named libmdbodbca.so is the ANSI driver, and the file named libmdbodbcw.so is the Unicode driver. Specify the desired driver by setting the Driver parameter in your odbc.ini file.

[MongoDBODBC]
DESCRIPTION = ODBC for MongoDB BI Connector
DRIVER      = /usr/local/lib/libmdbodbcw.so
TRACE       = Off
TRACEFILE   = stderr
READONLY    = yes
SERVER      = <server address>
PORT        = <port number>
USER        = <username>
PASSWORD    = <password>
DATABASE    = <dbname>
; optional SSL configuration
SSLKEY      = </path/to/.pem-key-file>
SSLCERT     = </path/to/ssl-certificate>
SSLMODE     = DISABLED|PREFERRED|REQUIRED
SSLCA       = </path/to/ssl-ca-list-file>
SSLCAPATH   = </path/to/ssl-ca-file-directory>
SSLCIPHER   = </path/to/ssl-cipher-file>
RSAKEY      = </path/to/rsa-public-key-file>

The previous example contains only one DSN, but it is possible to include multiple DSNs in an odbc.ini file.

The following table describes the parameters used in the previous example.

For the complete list of ODBC parameters, see Connector/ODBC Connection Parameters.

Your DSN is now ready to use. If you wish to test your DSN, proceed to step 3.

Install unixODBC

Install unixODBC with your preferred package manager.

On Ubuntu:

sudo apt-get install unixodbc

On RHEL:

sudo yum install unixODBC

Alternatively, you can download binaries from the unixODBC website.

Test with iusql

The unixODBC package includes an SQL client called iusql. You can use it to test your DSN.

The following example uses iusql to connect to the MongoDBODBC DSN, then looks for tables in a database named test:

iusql -v MongoDBODBC

SQL> use test;
SQL> show tables;