> This page location: /docs.md > /docs/tools-and-connectors.md > /docs/sql-interface.md > /docs/sql-interface/sql-interface-install.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: linux-macos, windows
-->

# SQL Interface Server Setup

You can use the MongoDB SQL Interface with an Atlas dedicated cluster, an Atlas federated database instance, or a self-managed [Enterprise Advanced (EA)](http://www.mongodb.com/products/self-managed/enterprise-advanced?tck=docs) database. Choose your deployment type to get started:

## Prerequisites

- A [MongoDB database user](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-mongodb-users) with which to connect.

## Procedure

You get the SQL Interface connection string for a federated database instance from the connection dialog box on the federated database instance card. This is the only place to get it.

1. In Atlas, go to your federated database instance for your project.

   If it's not already displayed, select the organization that contains your project from the  Organizations menu in the navigation bar.

   If it's not already displayed, select your project from the Projects menu in the navigation bar.

   In the sidebar, click Data Federation under the Services heading.

   The [Data Federation](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2FdataFederation) page displays.

2. On the federated database card, click Connect.

   A connection dialog box opens.

3. In the connection dialog box, click Atlas SQL.

4. Select your driver.

   From the Select your driver dropdown, select the driver that matches your BI (Business Intelligence) tool.

   | Driver | BI Tool |
   | --- | --- |
   | Power BI Connector | [Power BI Desktop](https://learn.microsoft.com/en-us/power-bi/fundamentals/desktop-get-the-desktop/) |
   | Tableau Connector | [Tableau](https://www.tableau.com/) Desktop or Server |
   | JDBC Driver | JDBC-supported tool such as DBeaver, DataGrip, or a Maven project |
   | ODBC Driver | ODBC-supported tool such as Excel |

5. Copy connection string.

   Select a database from the Database dropdown.

   Click  to copy the connection string. You'll need this when you connect your BI (Business Intelligence) tool.

   Click Done.

## Prerequisites

- 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 on an Atlas dedicated cluster, 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.

- A dedicated cluster, `M10` and above, running MongoDB 6.0 or later. To review every requirement, see [MongoDB SQL Interface Overview.](https://www.mongodb.com/docs/sql-interface/index.md#std-label-connect-with-sql-overview)

- To generate a schema, a database user with the `read` privilege on the `__mdb_internal_sqlinterface` database. The MongoDB SQL Schema Builder CLI reads this database before it processes any schema and exits if the read fails. To review every privilege that the CLI requires, see [MongoDB SQL Schema Builder CLI.](https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md#std-label-sql-schema-builder-cli)

## Procedure

Enable the SQL Interface on the cluster before you connect. Enabling is per cluster.

You can enable the SQL Interface from the Atlas UI or with the Atlas Administration API. To use the API, skip to [Enable with the Atlas Administration API.](https://www.mongodb.com/docs/sql-interface/connect-with-sql-composable.md#std-label-sql-dedicated-enable-api)

### Enable in the Atlas UI

1. In Atlas, go to the Clusters page for your project.

   If it's not already displayed, select the organization that contains your desired project from the  Organizations menu in the navigation bar.

   If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

   In the sidebar, click Clusters under the Database heading.

   The [Clusters](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fclusters) page displays.

2. On the cluster card, click Connect.

   A connection dialog box opens.

3. In the connection dialog box, click Atlas SQL.

4. Click Configure Atlas SQL.

   This button appears when the SQL Interface is off. It opens the same cluster configuration form as Edit Configuration.

5. Expand Additional Settings.

   Under Advanced Settings, set Enable Atlas SQL Interface (M10 and up) to on.

   The toggle appears only for eligible clusters. If you don't see it, confirm that the cluster is a dedicated cluster, `M10` and above, running MongoDB 6.0 or later.

6. Click Review Changes, then apply the change.

   The review page lists Atlas SQL Interface with its original and new state, Disabled and Enabled.

   **Note:**

   Enabling can take a few minutes to take effect.

### Enable with the Atlas Administration API

**Note:**

The endpoints are in preview and require the `Accept: application/vnd.atlas.preview+json` header. To learn more about resource versions, see [Versioned Atlas Administration API Overview](https://www.mongodb.com/docs/atlas/api/versioned-api-overview.md#std-label-api-versioning-overview). For the full reference, see [Atlas Administration API v2.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/)

To enable the SQL Interface using the Atlas Administration API, use the following procedure. Authenticate with a service account access token; to generate one, see [Generate Service Account Token.](https://www.mongodb.com/docs/atlas/api/service-accounts/generate-oauth2-token.md#std-label-generate-oauth2-token-atlas)

1. Confirm the cluster is supported.

   Send a `GET` request to read the current status:

   ```shell
   curl --include --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Accept: application/vnd.atlas.preview+json" \
     -X GET "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/sqlInterface"
   ```

   For a supported cluster, the response resembles the following:

   ```json
   {
     "status": "OFF",
     "supported": true
   }
   ```

   Atlas omits `unsupportedReason` when the cluster supports the SQL Interface. If `supported` is `false`, the field is present and explains why. To learn what each value means, see [Dedicated Cluster Considerations.](https://www.mongodb.com/docs/sql-interface/connect-with-sql-composable.md#std-label-sql-dedicated-enablement-reference)

2. Turn on the SQL Interface.

   Send a `PATCH` request with `status` set to `ON`:

   ```shell
   curl --include --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Accept: application/vnd.atlas.preview+json" \
     --header "Content-Type: application/vnd.atlas.preview+json" \
     --data '{ "status": "ON" }' \
     -X PATCH "https://cloud.mongodb.com/api/atlas/v2/groups/{groupId}/clusters/{clusterName}/sqlInterface"
   ```

   A successful request returns the updated status. Status propagation is asynchronous, so use the `GET` endpoint to confirm the state Atlas has applied.

   To turn the SQL Interface off, send the same `PATCH` request with `status` set to `OFF`.

### Generate a Schema

Dedicated clusters manage schemas with the MongoDB SQL Schema Builder CLI only, the same way self-managed [Enterprise Advanced (EA)](http://www.mongodb.com/products/self-managed/enterprise-advanced?tck=docs) deployments do. After you enable the SQL Interface, download and run the CLI to generate a schema for the collections that you want to query. To learn more, see [MongoDB SQL Schema Builder CLI.](https://www.mongodb.com/docs/sql-interface/schema/schema-builder-cli.md#std-label-sql-schema-builder-cli)

1. Download the MongoDB SQL Schema Builder.

   Download the MongoDB SQL Schema Builder for your operating system from the [MongoDB download center.](https://www.mongodb.com/try/download/sql-schema-builder/)

2. Run the MongoDB SQL Schema Builder.

   ### Linux/MacOS

   Move the downloaded file to a directory of your choice and rename it to `mongodb-schema-manager`.

   Go to the directory where you placed the file and run the following command to make the MongoDB SQL Schema Builder executable:

   ```bash
   chmod +x mongodb-schema-manager
   ```

   Run the MongoDB SQL Schema Builder with the connection string that you copy from the Atlas UI. This command generates or regenerates the schema for your collections within the database.

   ```bash
   ./mongodb-schema-manager --uri 'mongodb+srv://<db_username>:<db_password>@<cluster-host>/<database>'
   ```

   Look for the `__sql_schemas` collection in your database to verify the created SQL schema. Inside this collection, there is a document for each collection with its schema map and data type assignments.

### Dedicated Cluster Considerations

The following applies only to SQL Interface on dedicated clusters.

- Atlas allows schema generation and refresh for the cluster through the MongoDB SQL Schema Builder CLI. To learn more, see [Schema Management.](https://www.mongodb.com/docs/sql-interface/schema-management.md#std-label-sql-schema-management)

- Client applications, including ODBC (Open Database Connectivity) and JDBC (Java Database Connectivity) driver connections, can connect to the cluster through the SQL Interface after you enable it for the cluster and a schema exists. To install a driver, see [SQL Interface Driver Setup](https://www.mongodb.com/docs/sql-interface/install-driver.md#std-label-install-sql-interface-driver). To connect a BI (Business Intelligence) tool, see [Connect Your SQL Tool to MongoDB.](https://www.mongodb.com/docs/sql-interface/connect.md#std-label-sql-connect)

- Atlas uses the reserved [internal database](https://www.mongodb.com/docs/atlas/reference/internal-database.md#std-label-cloud-system-databases) `__mdb_internal_sqlinterface`. Don't modify or drop it.

- When you turn the SQL Interface off, client applications lose access and schemas can't be updated or used until you turn the SQL Interface back on.

#### Atlas Administration API Error Codes

| Status | Error Code | Cause and Resolution |
| --- | --- | --- |
| `400` | `CLUSTER_INVALID_STATE` | The cluster is in a state that cannot accept SQL Interface changes, such as `CREATING`, `UPDATING`, `DELETING`, `REPAIRING`, or `PAUSED`. Wait for the cluster to become idle, then retry the request. |
| `409` | `TENANT_SQL_INTERFACE_NOT_SUPPORTED` | The cluster's version, tier, or type does not support the SQL Interface. Use the `GET` endpoint to read `unsupportedReason`, then resolve the underlying constraint. |
| `409` | `SQL_INTERFACE_DISABLED_FOR_CLUSTER` | The SQL Interface is `OFF` for the cluster. Enable the SQL Interface before you request schema metadata. |

#### Unsupported Reasons

When `supported` is `false`, the `unsupportedReason` field contains one of the following values:

| Value | Meaning |
| --- | --- |
| `UNSUPPORTED_TIER` | The cluster tier does not support the SQL Interface. The feature requires a dedicated cluster, `M10` and above. |
| `UNSUPPORTED_TYPE` | The cluster type does not support the SQL Interface. Flex clusters return this value. Use a dedicated cluster instead. |
| `UNSUPPORTED_MONGODB_VERSION` | The cluster runs a MongoDB version earlier than 6.0. Upgrade the cluster to MongoDB 6.0 or later. |

## Prerequisites

- A [MongoDB database user](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-mongodb-users) with which to connect.

## Procedure

For local or self-managed deployments, you must generate a schema by downloading and running the MongoDB SQL Schema Builder. To learn more, see [the MongoDB SQL Schema Builder README.](https://translators-connectors-releases.s3.amazonaws.com/mongodb-schema-manager/docs/MongoDB_Schema_Manager-overview.pdf)

1. Download the MongoDB SQL Schema Builder.

   Download the MongoDB SQL Schema Builder for your operating system from the [MongoDB download center.](https://www.mongodb.com/try/download/sql-schema-builder/)

2. Run the MongoDB SQL Schema Builder.

   ### Linux/MacOS

   Move the downloaded file to a directory of your choice and rename to `mongodb-schema-manager`.

   Go to the directory where you placed the file and run the following command to make the MongoDB SQL Schema Builder executable:

   ```bash
   chmod +x mongodb-schema-manager
   ```

   Run the MongoDB SQL Schema Builder using a terminal command with your connection string like the following example. This command generates or regenerates the schema for your collections within the database.

   ```bash
   ./mongodb-schema-manager --uri 'mongodb://<db_username>:<db_password>@<host>:<port>/<database>?authSource=admin'
   ```

   Look for the `__sql_schemas` collection in your database to verify the created SQL schema. Inside this collection, there will be a document for each collection with its schema map and data type assignments.

## Next Steps

After you configure your database to accept SQL connections, you can [install the correct driver for your BI tool.](https://www.mongodb.com/docs/sql-interface/install-driver.md#std-label-install-sql-interface-driver)
