> This page location: /docs.md > /docs/tools-and-connectors.md > /docs/sql-interface.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  other tabs: macosarm, macosintel, ubuntu, windows
-->

# Transition from BI Connector to SQL Interface

This guide covers migrating from both the [MongoDB Connector for BI](https://www.mongodb.com/docs/bi-connector/current/) and the Atlas BI Connector to the newer [SQL Interface.](https://www.mongodb.com/docs/sql-interface/index.md#std-label-connect-with-sql-overview)

**Important:**

The [MongoDB Connector for BI](https://www.mongodb.com/docs/bi-connector/current/) 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.](https://www.mongodb.com/docs/sql-interface/index.md#std-label-connect-with-sql-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](https://www.mongodb.com/docs/atlas/data-federation/supported-unsupported/limitations.md#std-label-df-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](https://www.mongodb.com/docs/sql-interface/transition-bic-to-atlas-sql.md#std-label-bic-asql-transition-report-tool) to help plan your transition.

### Prerequisites

Prerequisites depend on where you migrate to. To compare the Atlas destinations, see [MongoDB SQL Interface Overview.](https://www.mongodb.com/docs/sql-interface/index.md#std-label-connect-with-sql-overview)

- **Atlas Dedicated cluster:** a [MongoDB database user](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-mongodb-users) with which to connect. To enable the SQL Interface, you also need an Atlas user with the [`Project Cluster Manager`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Cluster-Manager) or [`Project Replica Set Manager`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Replica-Set-Manager) role.

- **Atlas Federated Database Instance:** a federated database instance containing queryable data and a [MongoDB database user](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-mongodb-users) 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 (Uniform Resource Identifier), 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.

   ### MacOS (ARM)

   Download the [MongoDB MongoSQL Readiness Report Tool.](https://translators-connectors-releases.s3.amazonaws.com/transition-readiness-report/AtlasSQLReadinessReport-macos-arm)

2. Grant execution permission to the Readiness Report Tool.

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

   ### MacOS (ARM)

   ```sh
    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:

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

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

   Download `mongosql.gz`.

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

4. (Optional) Copy your cluster URI.

   Providing your Atlas cluster URI (Uniform Resource Identifier) 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 (Uniform Resource Identifier):

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

   Click Connect.

   Select Shell from the list of connection options.

   Copy only your connection URI (Uniform Resource Identifier).

   The connection URI (Uniform Resource Identifier) 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 (Uniform Resource Identifier).

   - You must include your database username.

   - You must include either `--input`, `--uri`, or both. If you include your URI (Uniform Resource Identifier), 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 (Domain Name System) 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:

   ```sh
   <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.](https://www.mongodb.com/docs/sql-interface/connect-with-sql-composable.md#std-label-connect-with-sql-composable)

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.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-sql-connect)

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.](https://www.mongodb.com/docs/sql-interface/query-with-asql-statements.md#std-label-asql-write-asql-queries)

4. View your schema and adapt it if necessary.

   To learn more about schemas in the SQL Interface, see [Schema Management.](https://www.mongodb.com/docs/sql-interface/schema-management.md#std-label-sql-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.](https://www.mongodb.com/docs/sql-interface/language-reference.md#std-label-sql-reference)

## Troubleshoot the SQL Interface

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

- The MongoDB communities on [Reddit](https://www.reddit.com/r/MongoDB_Official/) or [Stack Overflow](https://stackoverflow.com/questions/tagged/mongodb)

- [Support](https://www.mongodb.com/services/support)

- [Professional Services](https://www.mongodb.com/services/consulting)

- Your [Customer Success](https://www.mongodb.com/services/customer-success-program) team
