Connect from the MySQL Client


New in version 2.2: The MongoDB Connector for BI now offers MySQL authentication plugins allowing you to connect with authentication but without TLS/SSL.

There are two options for authenticating your connection:

  1. Use an authentication plugin with either the SCRAM-SHA-1 or PLAIN authentication mechanism.


    The use of TLS/SSL is recommended as:

    • The SCRAM-SHA-1 mechanism hashes the passwords in the client plugin. However, all other data is in cleartext.
    • The PLAIN mechanism sends the password in cleartext.

    See C Authentication Plugin or Install the JDBC Authentication Plugin for more information on the plugins.

  2. Provide cleartext credentials for simple username/password authentication against a MongoDB database. This method uses MySQL’s built-in mysql_clear_password plugin.


    Authentication with mysql_clear_password requires the use of TLS/SSL. See Connect from MySQL with Authentication and TLS/SSL for more information.

The MongoDB Connector for BI requires authentication when running with --auth. When the MongoDB Connector for BI receives a connection with authentication credentials from a client, it passes those credentials through to the underlying MongoDB instance.

You can specify the following authentication options after your username as URI-style query parameters:

Connection Option Description

Specify the name of the database which stores the user’s credentials. If you do not specify this option, the MongoDB Connector for BI will default to the current database associated with the MySQL connection.

For authentication mechanisms such as PLAIN (LDAP) that delegate credential storage to other services, set the source value to $external.


Specify the mechanism that the MongoDB Connector for BI should use to authenticate the connection. Accepted values include:

The PLAIN (LDAP) mechanism requires MongoDB Enterprise, and requires that source be $external.


Neither Kerberos (GSSAPI) nor x.509 are supported.


To authenticate as the user grace with authentication mechanism PLAIN and using an external source, you would use the following username:


You can use the command-line MySQL client to connect to the MongoDB Connector for BI.

Connect from MySQL without Authentication or TLS/SSL

To connect to a mongosqld instance listening on the MySQL default port 3307, run the following command:

mysql --protocol tcp --port 3307

Connect from MySQL with Authentication

Install the authentication plugin as described on Install the C Authentication Plugin.

The following example uses the C authentication plugin to connect to a mongosqld instance listening on port 3307 as user reportsUser. The MySQL shell prompts for the password after the command has been entered.

mysql '--user=reportsUser?source=admin' --default-auth=mongosql_auth -p

This example assumes that the authentication plugin file is located in the default MySQL plugin folder. The location of the plugin folder varies by platform, but you can locate it by running the following command:

mysql_config --plugindir

Connect from MySQL with Authentication and TLS/SSL

To connect to a mongosqld instance listening on port 3307, as user grace using authentication mechanism PLAIN, and using specific TLS/SSL CA and x.509 certificates, run the following command:

mysql --enable-cleartext-plugin --protocol tcp --port 3307 \
  -u 'grace?mechanism=PLAIN&source=$external' \
  --ssl-ca=/path_to_the_CAcert/ca.crt \
  --ssl-key=/path_to_my_certificate_key/mysql.key \
  --ssl-cert=/path_to_my_client_certificate/mysql.crt \

If using the $external authentication source, wrap your username in single quotes or escape the $ character with a backslash to prevent your shell from performing interpolation.

Authentication requires your client to send your password in plain text. To send the password in plain text, either:

  • Use the --enable-cleartext-plugin option shown in the previous example, or
  • Set the environment variable LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN=1.

See the MySQL documentation for additional details on enabling the MySQL cleartext plugin.