> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inflection.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Databricks Setup: Service Principal

> Prepare Databricks for Inflection with a service principal: read grants, connection fields, and Databricks storage for import, plus export setup.

> [!NOTE]
>
> This page covers what your Databricks administrator sets up. The steps you take inside Inflection are in [Import from Data Warehouse](/connections/import-from-data-warehouse.md) and [Export to Data Warehouse](/connections/export-to-data-warehouse.md).

> [!NOTE]
>
> This page covers importing from Databricks with a **service principal**, and Databricks export. If your workspace imports over Delta Sharing, see [Databricks Delta Sharing](/connections/warehouses/databricks.md). To switch your import to the other method, contact your Inflection customer success team.

## Connection Fields

Import and export connections use the same fields.

| Field | What to enter |
| - | - |
| **Client id** | The OAuth Application ID of the service principal. In Databricks: **Settings**, then **Identity and access**, then **Service principals**, then your service principal. |
| **Client secret** | The OAuth secret you generated for the service principal in [Step 1](#step-1-create-a-service-principal). Databricks shows it only once. |
| **Host** | The bare hostname of your workspace, for example `dbc-xxxxxxxx-xxxx.cloud.databricks.com`. Do not include `https://`. In Databricks: **SQL Warehouses**, then your warehouse, then **Connection details**, where it is labeled **Server hostname**. |
| **Catalog** | For import, the catalog that holds your source schemas. For export, the catalog Inflection writes the export tables to. Browse your catalogs under **Catalog** in Databricks. |
| **Http path** | The HTTP path of your SQL warehouse, for example `/sql/1.0/warehouses/xxxxxxxxxxxxxxxx`. In Databricks: **SQL Warehouses**, then your warehouse, then **Connection details**, on the same screen as the hostname. |
| **Schema** (export only) | The schema where Inflection creates the export tables. |

![SQL warehouse Connection details tab showing Server hostname and HTTP path](https://mintcdn.com/inflection-4b2c0de4/a-mNPLy9KuYEMsUK/images/connections/warehouses/databricks-service-principal/01.png?fit=max\&auto=format\&n=a-mNPLy9KuYEMsUK\&q=85\&s=c0d305a80af36a8bd0239fa374b9dd11)

## Prepare Databricks for Import

Inflection signs in to your workspace as a service principal and reads your tables through your SQL warehouse. Each sync writes its results into an Inflection-owned storage location through an external location that you create once. Inflection does not create tables or views in your catalog.

### Prerequisites

* A **Unity Catalog-enabled** Databricks workspace on AWS.
* A **service principal** created only for Inflection, with an OAuth client ID and secret. See [Step 1: Create a Service Principal](#step-1-create-a-service-principal).
* A **SQL warehouse** for Inflection's queries to run on. Your tables stay in your catalog. The service principal needs read access on your catalog and schemas, and **Can use** on the warehouse. See [Step 2: Grant Read Access](#step-2-grant-read-access).
* Someone who can create a storage credential and an external location in Unity Catalog, needed once: a **metastore admin**, or a user with `CREATE STORAGE CREDENTIAL` and `CREATE EXTERNAL LOCATION` on the metastore. See [Set Up Databricks Storage](#step-4-set-up-databricks-storage). Inflection's service principal never gets these privileges.
* Source tables or views that meet the [source table requirements](/connections/import-from-data-warehouse.md#source-table-requirements) in Import from Data Warehouse.

> [!NOTE]
>
> **What is a metastore admin?** A metastore admin is a Databricks role, not a credential, so there is nothing to generate or copy. It belongs to the person or group that manages Unity Catalog for your Databricks account. To see who has it, your Databricks account admin opens the account console, clicks **Catalog**, selects your metastore, and checks **Metastore admin**. Inflection's service principal never needs this role.

### Step 1: Create a Service Principal

1. In Databricks, open **Settings**, then **Identity and access**, then **Service principals**.
2. Click **Add service principal** and give it a name, for example `inflection-sync`.
3. Open the service principal. Its **Application ID** is the client ID you enter in Inflection.
4. Go to the **Secrets** tab and click **Generate secret**.
5. Copy the **Client ID** and the **Secret**. The secret is shown only once.

![Databricks Service principals list with the Add service principal dialog](https://mintcdn.com/inflection-4b2c0de4/a-mNPLy9KuYEMsUK/images/connections/warehouses/databricks-service-principal/02.png?fit=max\&auto=format\&n=a-mNPLy9KuYEMsUK\&q=85\&s=86734a50c0696b8788d857300a6d3cbd)

![Service principal details page showing the Application Id and the Secrets tab](https://mintcdn.com/inflection-4b2c0de4/a-mNPLy9KuYEMsUK/images/connections/warehouses/databricks-service-principal/03.png?fit=max\&auto=format\&n=a-mNPLy9KuYEMsUK\&q=85\&s=6f7b959ae05f171a21746edd20811496)

> [!TIP]
>
> Databricks OAuth secrets expire. Note the expiry date and replace the secret in Inflection before it lapses, or syncs stop. See [Manage and Troubleshoot Data Warehouse Syncs](/connections/manage-data-warehouse-syncs.md) for how to change credentials on a live connection.

### Step 2: Grant Read Access

Do this as a Databricks workspace admin, or another user who can manage the SQL warehouse and grant on the catalog.

**Give the service principal Can use on the SQL warehouse**

First, give the service principal **Can use** permission on the SQL warehouse, so it can run queries:

1. In Databricks, click **SQL Warehouses** and select the warehouse Inflection will use.
2. Click **Permissions**.
3. Search for the service principal by name, choose **Can use**, and click **Add** to add the service principal.

![SQL warehouse Manage permissions dialog with service principals added as Can use](https://mintcdn.com/inflection-4b2c0de4/a-mNPLy9KuYEMsUK/images/connections/warehouses/databricks-service-principal/04.png?fit=max\&auto=format\&n=a-mNPLy9KuYEMsUK\&q=85\&s=381f633ca8c722b082b28469cbe0ec5f)

**Find your catalog and schema names**

Inflection reads tables you already have. You do not need to create a new catalog or schema for import. In Databricks, click **Catalog** in the left sidebar. The tree lists your catalogs, the schemas inside each catalog, and the tables inside each schema. A table's full name is `catalog.schema.table`, for example `main.marketing.contacts`. Note the catalog and every schema that holds a table Inflection should read. Enter that catalog as **Catalog** on the Connect step.

![Databricks Catalog explorer with a catalog expanded to its schemas and tables](https://mintcdn.com/inflection-4b2c0de4/a-mNPLy9KuYEMsUK/images/connections/warehouses/databricks-service-principal/05.png?fit=max\&auto=format\&n=a-mNPLy9KuYEMsUK\&q=85\&s=15fcadafaa8a4e6cf6caa5b6eee44ffd)

**Run the grants**

Open the **SQL Editor** and run the following as a user who can grant on the catalog. Replace the catalog and schema names, and use the service principal's **Application ID** as the grantee (see [Step 1](#step-1-create-a-service-principal)).

```sql theme={null}
GRANT USE CATALOG ON CATALOG <your_catalog> TO `<application_id>`;
GRANT USE SCHEMA, SELECT ON SCHEMA <your_catalog>.<your_schema> TO `<application_id>`;
```

If your source tables are in more than one schema, run the second statement once for each schema.

**Check the grants (optional)**

```sql theme={null}
SHOW GRANTS `<application_id>` ON SCHEMA <your_catalog>.<your_schema>;
```

The result should list `USE SCHEMA` and `SELECT`. If a statement fails, see [Troubleshooting](#troubleshooting).

### Step 3: Connect in Inflection

Enter the [connection fields](#connection-fields) on the Connect step. If your workspace restricts access by IP, first add the addresses listed under **Network access (optional)** on the Connect step to your workspace IP access list. Click **Test connection**. On success you see **Connected to Databricks. Credentials verified.** If the test fails or times out, see [Troubleshooting](#troubleshooting). Then continue with [Step 2: Set Up Your Data](/connections/import-from-data-warehouse.md#step-2-set-up-your-data) in Import from Data Warehouse, and come back to [Step 4](#step-4-set-up-databricks-storage) when you reach **Save & activate**.

![Connect step for Databricks with credentials verified](https://mintcdn.com/inflection-4b2c0de4/a-mNPLy9KuYEMsUK/images/connections/warehouses/databricks-service-principal/06.png?fit=max\&auto=format\&n=a-mNPLy9KuYEMsUK\&q=85\&s=4821d46ecb5f1b5b500d17d0de8ec034)

### Step 4: Set Up Databricks Storage

Do this when you reach **Save & activate**, which is [Step 3: Save and Activate](/connections/import-from-data-warehouse.md#step-3-save-and-activate) in the import wizard, after you have set up your data. It is a one-time setup in the **Databricks storage** card. Keep Databricks and Inflection open side by side, since you copy values between them. Your SQL warehouse writes each sync's export into Inflection's storage through an external location in your workspace. The connection cannot be activated until the storage is verified.

In Inflection, the **Databricks storage** card shows values generated for your workspace: an **IAM role ARN**, and **External location SQL** that already includes your storage location and service principal. Copy them from the card.

![Databricks storage card on Save & activate with the IAM role ARN, External ID, and External location SQL](https://mintcdn.com/inflection-4b2c0de4/a-mNPLy9KuYEMsUK/images/connections/warehouses/databricks-service-principal/07.png?fit=max\&auto=format\&n=a-mNPLy9KuYEMsUK\&q=85\&s=873dcdd70968720c20204421a8f55ec8)

**Part 1: Create a storage credential**

1. **In Inflection:** in the **Databricks storage** card, click **Copy** next to **IAM role ARN**.
2. **In Databricks:** go to **Catalog**, then **External Data**, then the **Credentials** tab, and click **Create credential**.
   1. Select **Storage Credential**.
   2. For **Credential Type**, select **AWS IAM Role**.
   3. Enter a **Credential name**, for example `inflection_storage`. Remember it; you need it in Part 2.
   4. Paste the role ARN into **IAM role (ARN)** and click **Create**. (You do not need to edit any IAM role yourself. Inflection manages the trust policy on its side.)
   5. Databricks shows **Credential created** with an **External ID** and a trust policy. Copy the **External ID**.
3. **In Inflection:** paste the value into **External ID** and click **Save external id**. The field shows **Saved**.

If the credential can't be created, see [Troubleshooting](#troubleshooting).

![Databricks Create a new credential dialog with Storage Credential and AWS IAM Role selected](https://mintcdn.com/inflection-4b2c0de4/a-mNPLy9KuYEMsUK/images/connections/warehouses/databricks-service-principal/08.png?fit=max\&auto=format\&n=a-mNPLy9KuYEMsUK\&q=85\&s=74df3e38d3b5bdc119b8be8a8d9d4670)

![Databricks Credential created dialog with the External ID](https://mintcdn.com/inflection-4b2c0de4/a-mNPLy9KuYEMsUK/images/connections/warehouses/databricks-service-principal/09.png?fit=max\&auto=format\&n=a-mNPLy9KuYEMsUK\&q=85\&s=55cbc9174a8e6e0e59a81f43fcec28a4)

**Part 2: Create the external location**

1. **In Inflection:** in the **Databricks storage** card, click **Copy code** on **External location SQL**. Inflection has already filled in the location name, the storage URL, and your service principal's client ID. Only `<your_storage_credential>` is left for you to fill in.
2. **In Databricks:** open the **SQL Editor**, paste the SQL, and replace `<your_storage_credential>` with the credential name from Part 1.
3. Run it as a **metastore admin** (see What is a metastore admin? under [Prerequisites](#prerequisites)), or as a user with `CREATE EXTERNAL LOCATION` on the metastore. It creates the external location and grants the service principal `READ FILES` and `WRITE FILES` on it. The result shows **OK**.

The SQL looks like this. Use the version from Inflection, which has your values filled in.

```sql theme={null}
CREATE EXTERNAL LOCATION IF NOT EXISTS `inflection_s3_<id>`
  URL 's3://<inflection-bucket>/warehouse_type=databricks/'
  WITH (STORAGE CREDENTIAL `<your_storage_credential>`);
GRANT READ FILES, WRITE FILES ON EXTERNAL LOCATION `inflection_s3_<id>` TO `<client_id>`;
```

![External location SQL run in the Databricks SQL Editor with an OK result](https://mintcdn.com/inflection-4b2c0de4/a-mNPLy9KuYEMsUK/images/connections/warehouses/databricks-service-principal/10.png?fit=max\&auto=format\&n=a-mNPLy9KuYEMsUK\&q=85\&s=69c7144c84e48e32b8ee777712158751)

If the SQL fails, see [Troubleshooting](#troubleshooting).

**Verify storage**

1. **In Inflection:** click **Verify storage**. Inflection writes a small test file through the external location.
2. On success, the activation requirement **Databricks storage is verified** turns green and **Activate connection** is enabled.

If verification fails right after you save the External ID, wait a few seconds and click **Verify storage** again. You can also save the connection as a draft, finish the storage setup later, and come back. If it keeps failing, see [Troubleshooting](#troubleshooting).

![Databricks storage verified and the Activate checklist on Save & activate](https://mintcdn.com/inflection-4b2c0de4/a-mNPLy9KuYEMsUK/images/connections/warehouses/databricks-service-principal/11.png?fit=max\&auto=format\&n=a-mNPLy9KuYEMsUK\&q=85\&s=e439285bab33b5d4f7faa491f36d5fb6)

## Prepare Databricks for Export

1. Create a service principal for Inflection and note its client ID and client secret.
2. Grant it the minimum permissions on the target catalog and schema. Inflection needs `USE CATALOG` and `USE SCHEMA` to locate the destination, and table-level `INSERT`, `UPDATE`, `DELETE`, and `ALTER` on the export tables. These do not give access to your other data.

   ![Minimum permissions required on the target catalog for the Inflection service principal](https://mintcdn.com/inflection-4b2c0de4/N4VRWuxaoalXbMy_/images/connections/warehouses/databricks/03.png?fit=max\&auto=format\&n=N4VRWuxaoalXbMy_\&q=85\&s=bdc501ed2291ed42601db570e5ec45bb)

Then add the export connection in Inflection: click **Connections**, open **Data Connections**, click **Add new connection**, choose **Databricks** under **Data Warehouse**, and select **Export Data to Databricks**. Enter the [connection fields](#connection-fields), including **Schema**. See [Export to Data Warehouse](/connections/export-to-data-warehouse.md) for what gets exported and how to manage the connection.

## Troubleshooting

> **The import connection test fails or times out.**
>
> Check the **Host** field. Enter the bare hostname only, for example `dbc-xxxxxxxx-xxxx.cloud.databricks.com`. A value that starts with `https://` causes the test to time out. Also confirm the **Http path** belongs to a running SQL warehouse, the client secret has not expired, and, if your workspace restricts access by IP, that the addresses under **Network access (optional)** on the Connect step are in your workspace IP access list.

> **The wizard says it can't list my tables yet.**
>
> Pick the schema to read from under the search box, or click **+ Add schema**, then open **Warehouse access** and check access. If the tables still do not appear, run the `SHOW GRANTS` check from [Step 2](#step-2-grant-read-access) and confirm the service principal has `USE CATALOG` on the catalog and `USE SCHEMA` and `SELECT` on the schema. You can also click **Add table by name**.

> **Verify storage fails.**
>
> Confirm the storage credential type is **AWS IAM Role** and that you pasted the External ID from that credential into Inflection and clicked **Save external id**. Confirm the external location SQL ran as a metastore admin, or a user with `CREATE EXTERNAL LOCATION`, with your credential name in place of `<your_storage_credential>`. If you just saved the External ID, wait a few seconds and try again.

> **My new export connection does not appear in the Connections list.**
>
> Check the **Active only** toggle above the list. A connection waiting for activation is inactive and is hidden while the toggle is on.

> **I chose We draft a view for you and cannot create the view.**
>
> Inflection does not create objects in your workspace, so **Create it for me** is not offered on Databricks. Copy the drafted SQL, run it yourself in a schema you granted in [Step 2](#step-2-grant-read-access), then click **Verify it**. See [Choose a Sync Method](/connections/import-from-data-warehouse.md#choose-a-sync-method) in Import from Data Warehouse.

> **A GRANT statement fails with a permission error.**
>
> Run the statements as a user who owns the catalog or can grant on it, such as a workspace admin. Check that the catalog and schema names are exact, and that `<application_id>` is the service principal's **Application ID** (see [Step 1](#step-1-create-a-service-principal)), in backticks.

> **Verify it fails for a drafted view.**
>
> Confirm the view was created under the exact name shown in Inflection, and in a schema the service principal can read. Run the `SHOW GRANTS` check from [Step 2](#step-2-grant-read-access) on that schema, and run the Step 2 grant for it if needed.

> **I can't create the storage credential.**
>
> Creating a storage credential needs a metastore admin, or a user with `CREATE STORAGE CREDENTIAL`. See What is a metastore admin? under [Prerequisites](#prerequisites). Also confirm you selected **Storage Credential** and **AWS IAM Role**, and pasted the full role ARN from Inflection.

> **The external location SQL fails.**
>
> Run it as a metastore admin, or a user with `CREATE EXTERNAL LOCATION` on the metastore and access to the storage credential. Confirm you replaced `<your_storage_credential>` with the credential name from Part 1.

> **Which import method does my workspace use?**
>
> Check the Connect step of the import wizard. If it asks for **Client id**, **Client secret**, **Host**, **Catalog**, and **Http path**, you use a service principal and this page applies. If it asks for a **Provider name** and **Share name**, you use Delta Sharing; see [Databricks Delta Sharing](/connections/warehouses/databricks.md). To switch methods, contact your Inflection customer success team.

Still stuck after these checks? Contact your Inflection customer success team.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.