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
/
Tools
/
SQL Interface
Docs Home
/
Tools
/
SQL Interface
Docs Home
/
Tools
/
SQL Interface

Transition from BI Connector to SQL Interface

This guide covers migrating from both the MongoDB Connector for BI and the Atlas BI Connector to the newer SQL Interface.

Important

The MongoDB Connector for BI and the Atlas BI Connector reached end of life (EOL) in September 2026.

SQL Interface

Similar to the BI Connector, SQL Interface enables you to analyze data from your MongoDB deployments using a variety of SQL-based tools, such as Tableau and Power BI.

Compared to the BI Connector, the SQL Interface offers the following advantages:

  • You can connect directly to an Atlas dedicated cluster, with no federated database instance required. This is the recommended path for most Atlas connections.

  • Through an Atlas federated database instance, you can read data from sources other than Atlas clusters. Use this path when a single query must span more than one data source.

  • Schemas are persisted separately and can be updated without disrupting SQL querying capabilities.

  • You can use custom MongoDB connectors for Tableau and Power BI.

To compare the two Atlas connection paths, see MongoDB SQL Interface Overview.

SQL Interface Limitations

  • The SQL Interface provides read-only access.

  • MongoSQL is the only supported dialect. MongoSQL is SQL-92 compatible. Other SQL dialects are not supported.

  • If you connect through an federated database instance, all Atlas Data Federation limitations also apply. They do not apply to a direct connection to a dedicated cluster.

Prepare to Transition to SQL Interface

Before you transition from the BI Connector to the SQL Interface, confirm that your deployment meets the prerequisites for your migration destination. MongoDB also recommends that you generate a Transition Readiness Report to help plan your transition.

Prerequisites

Prerequisites depend on where you migrate to. To compare the Atlas destinations, see MongoDB SQL Interface Overview.

  • Atlas Dedicated cluster: a MongoDB database user with which to connect. To enable the SQL Interface, you also need an Atlas user with the Project Cluster Manager or Project Replica Set Manager role.

  • Atlas Federated Database Instance: a federated database instance containing queryable data and a MongoDB database user with which to connect.

  • Self-managed Enterprise Advanced (EA) deployment: a MongoDB database user with the required database privileges. No Atlas project role is required.

Generate a Transition Readiness Report

MongoDB provides a MongoSQL Transition Readiness Tool to help you plan your move from the BI Connector to the SQL Interface. The tool generates a report based on your past BI Connector usage, providing real-time schema analysis and suggestions and highlighting queries that need syntax changes to run properly using MongoSQL.

To generate a report, you must provide the tool with at least one of the following details:

  • Your BI Connector logs, for query analysis.

  • Your cluster URI, for schema analysis.

You can analyze your queries, your schema, or both.

1

Download the MongoSQL Readiness Report Tool.

Select the tab for your operating system below and download the executable file.

2

Grant execution permission to the Readiness Report Tool.

If the file doesn't have execution permission already, grant it.

 chmod +x <executable-filename>
 chmod +x <executable-filename>
 chmod +x <executable-filename>
3

(Optional) Download and decompress your BI Connector logs.

Providing your BI Connector logs enables the Readiness Report Tool to report on the following information:

  • Historical query data, such as volume and frequency.

  • Query syntax that will fail in MongoSQL.

  • Collection fields with data types unknown to relational databases.

For the on-premises BI Connector, the logs are wherever you configured the mongosqld log path.

To download your Atlas BI Connector logs:

  1. In the Atlas UI, go to the Atlas cluster with the BI connection that you want to analyze.

  2. From your cluster's options (), select Download Logs.

  3. Download mongosql.gz.

  4. Create a new directory, then decompress mongosql.gz into it.

4

(Optional) Copy your cluster URI.

Providing your Atlas cluster URI enables the Readiness Report Tool analyze your collection schemas and identify fields that contain data types unknown to SQL tools.

To find your Atlas cluster URI:

  1. In the Atlas UI, go to the cluster with the collections that you want to analyze.

  2. Click Connect.

  3. Select Shell from the list of connection options.

  4. Copy only your connection URI.

    The connection URI resembles: mongodb+srv://bicluster.example.mongodb.net/. Exclude the shell executable, mongosh, and any shell-specific command line options.

5

Generate a report.

In a terminal, run the Readiness Report Tool executable, providing your downloaded logs or your cluster URI.

  • You must include your database username.

  • You must include either --input, --uri, or both. If you include your URI, the Readiness Report Tool prompts you for your database user password.

  • You can specify an --output destination for your generated report. If you don't, it's generated in your current directory.

  • You can specify a --resolver to choose a DNS resolver for network requests. Possible values are: cloudflare, google, and quad9.

  • You can use --include or --exclude to narrow your list of namespaces. Glob syntax is supported. By default, all namespaces are included.

The --help option returns the full list of Readiness Report Tool options:

<executable-filename> --help
Options:
     -i, --input <INPUT>        Sets the input file or directory to analyze BIC logs (optional). One of `--input` or `--uri` must be provided, or both
     -o, --output <OUTPUT>      Sets the output directory (optional). If not specified, the current directory is used
         --uri <URI>            The Atlas cluster URI to analyze schema (optional). One of `--input` or `--uri` must be provided, or both
     -u, --username <USERNAME>  Username for authentication (optional). This is required if the username and password is not provided in the URI
         --quiet                Enables quiet mode for less output
         --resolver <RESOLVER>  The specified resolver (optional) [possible values: cloudflare, google, quad9]
         --include <INCLUDE>    A list of namespaces to include (optional). If not provided, all namespaces are included. Glob syntax is supported
         --exclude <EXCLUDE>    A list of namespaces to exclude (optional). If not provided, no namespaces are excluded
     -h, --help                 Print help (see more with '--help')
     -V, --version              Print version

The Readiness Report Tool organizes the output and generates a clickable index file so you can easily navigate the report.

Transition to SQL Interface

The underlying architecture of the SQL Interface is different from the BI Connector and you might need to adapt your schema or your queries.

To transition to the SQL Interface, identify existing BI Connector queries that fail on MongoSQL and update your schema or their syntax to fix them.

Warning

We recommend testing the full transition process in a sandbox environment before you make changes to your production environment. Transitioning from the BI Connector to the SQL Interface without adapting your schema or your queries might cause breaking changes.

1

Enable the SQL Interface on your Atlas cluster.

For most Atlas deployments, enable the SQL Interface directly on a dedicated cluster. This is the recommended migration destination and needs no federated database instance. Use a federated database instance instead when a single SQL query must span more than one data source.

To learn more about enabling and using the SQL Interface, see SQL Interface Server Setup.

2

Connect to your data with the SQL Interface.

To learn more about connecting with the SQL Interface, see Connect Your SQL Tool to MongoDB.

3

Test your queries.

Test your queries with your new SQL Interface connection to ensure they run and return the results you expect.

To learn more about querying with MongoSQL, see Query with MongoSQL Statements.

4

View your schema and adapt it if necessary.

To learn more about schemas in the SQL Interface, see Schema Management.

5

Adapt any failing queries.

Some query syntax might need to be changed when you transition from the BI Connector to the SQL Interface.

To learn more about MongoSQL query syntax, see MongoSQL Language Reference.

Troubleshoot the SQL Interface

The following MongoDB resources can help you troubleshoot your SQL Interface configuration:

Back
Overview
Next
Install
Rate this page

On this page