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

# Setting Up Databricks

> Connect a Databricks SQL warehouse to Credible

To connect Databricks to Credible you need a SQL warehouse and credentials for either a **personal access token (PAT)** or an **OAuth machine-to-machine (M2M) service principal**.

## Prerequisites

* A Databricks workspace with Unity Catalog enabled
* Permission to create or use a SQL warehouse
* Permission to create a personal access token, or workspace admin access to create an OAuth service principal

## Step 1: Find or Create a SQL Warehouse

Credible queries Databricks through a SQL warehouse.

1. In the Databricks workspace, go to **SQL Warehouses** in the left sidebar
2. Use an existing warehouse or click **Create SQL warehouse**
3. Give it a name (e.g., `credible-warehouse`) and pick a size — a `Small` Serverless warehouse is a good starting point
4. Click **Create**

Once the warehouse exists, open it and note the following from the **Connection details** tab:

* **Server hostname** — looks like `dbc-xxxxxxxx-xxxx.cloud.databricks.com`. This is the **Host** field in Credible.
* **HTTP Path** — looks like `/sql/1.0/warehouses/<warehouse-id>`. This is the **HTTP Path** field in Credible.

## Step 2: Create Credentials

Choose **one** of the following authentication methods.

### Option A: Personal Access Token (PAT)

Best for getting started or for connections owned by an individual user.

1. In Databricks, click your user avatar (top right) > **Settings**
2. Go to **Developer** > **Access tokens** > **Manage**
3. Click **Generate new token**
4. Add a comment (e.g., `credible`) and choose a lifetime
5. Click **Generate** and copy the token — you cannot view it again

<Note>
  Treat the PAT like a password. Anyone with the token can act as you in Databricks.
</Note>

### Option B: OAuth M2M Service Principal

Recommended for production. The connection is owned by a service principal rather than a person, so it survives user offboarding.

1. In Databricks, go to **Settings** > **Identity and access** > **Service principals**
2. Click **Add service principal**, name it (e.g., `credible-sp`), and create it
3. Open the service principal and go to the **Secrets** tab
4. Click **Generate secret** and copy both the **Client ID** and **Client Secret** — the secret is shown only once
5. Grant the service principal access to your SQL warehouse and Unity Catalog data:
   * In **SQL Warehouses**, open the warehouse, click **Permissions**, and grant the service principal **Can use**
   * In Unity Catalog, grant the service principal `USE CATALOG`, `USE SCHEMA`, and `SELECT` on the catalogs/schemas/tables you want Credible to read

## Step 3: Grant Data Access

Whichever identity you chose (your user for a PAT, or the service principal for OAuth), it needs Unity Catalog privileges on the data you plan to model. At a minimum:

* `USE CATALOG` on the target catalog
* `USE SCHEMA` on each schema
* `SELECT` on each table or view

You can grant these in the Databricks **Catalog Explorer** or via SQL:

```sql theme={null}
GRANT USE CATALOG ON CATALOG main TO `credible-sp`;
GRANT USE SCHEMA ON SCHEMA main.sales TO `credible-sp`;
GRANT SELECT ON SCHEMA main.sales TO `credible-sp`;
```

## Step 4: Connect in Credible

1. Go to `your-org.app.credibledata.com`
2. Navigate to your environment
3. Click **Add Connection**
4. Select **Databricks**
5. Fill in:
   * **Host** — the workspace hostname from Step 1
   * **HTTP Path** — the warehouse HTTP path from Step 1
   * **Default Catalog** — the Unity Catalog to use by default (e.g., `main`)
   * **Default Schema** — optional, the default schema within the catalog (e.g., `default`)
   * **Access Token** — paste the PAT from Step 2A, **or**
   * **OAuth Client ID** + **OAuth Client Secret** — paste the credentials from Step 2B
6. Click **Test Connection** to verify connectivity
7. Save the connection

<Note>
  Provide either a personal access token **or** OAuth client credentials, not both.
</Note>

## Troubleshooting

* **`Invalid access token` / `401 Unauthorized`** — The PAT has expired or was revoked. Generate a new one in Databricks user settings.
* **`PERMISSION_DENIED` on a table** — The user or service principal is missing `USE CATALOG`, `USE SCHEMA`, or `SELECT`. Grant the missing privilege in Unity Catalog.
* **Connection times out** — A Serverless warehouse may be cold-starting. Open the warehouse in Databricks and confirm it can start; for classic warehouses, ensure auto-stop hasn't paused it indefinitely.
* **`Catalog not found`** — Double-check the **Default Catalog** value matches a Unity Catalog the identity has `USE CATALOG` on.