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

# Databricks

> Connect Databricks to CloudThinker to review clusters, jobs, runs, notebooks, and catalog assets, and diagnose failed work

Connect your Databricks workspace to let CloudThinker agents review clusters, jobs, runs, notebooks, files, and catalog assets, run focused data queries, and diagnose failed work before anyone touches production.

Databricks authenticates with a **personal access token** for your workspace. Operational changes stay deliberate, approval-based decisions.

## Prerequisites

* A **Databricks workspace** and a user allowed to create personal access tokens in it.
* Optionally, a **SQL warehouse** if you want agents to run SQL queries.

## Setup

<Steps>
  <Step title="Create a personal access token">
    In your Databricks workspace, click your username in the top bar and select **Settings → Developer**. Next to **Access tokens**, click **Manage**, then **Generate new token**. Set a lifetime and copy the token.
  </Step>

  <Step title="Find your workspace URL and warehouse ID">
    The workspace URL is your Databricks address, such as `https://dbc-a1b2345c-d6e7.cloud.databricks.com`. For SQL queries, copy the warehouse's ID from **SQL Warehouses → your warehouse → Connection details** — it is the last segment of the **HTTP path**.
  </Step>

  <Step title="Add the connection in CloudThinker">
    Navigate to **Connections → Databricks** and enter:

    * **DATABRICKS\_HOST**: your workspace URL
    * **DATABRICKS\_TOKEN**: the personal access token
    * **DATABRICKS\_WAREHOUSE\_ID**: optional — only needed for SQL queries

    Click **Connect**. CloudThinker verifies the credentials and shows a **Connected** status.
  </Step>
</Steps>

<Warning>
  Databricks automatically revokes personal access tokens that have not been used for 90 days, and a token expires at the lifetime you set. Recreate the token and update the connection when either happens.
</Warning>

## Connection details

| Field                         | Description                                              | Example                                          |
| ----------------------------- | -------------------------------------------------------- | ------------------------------------------------ |
| **DATABRICKS\_HOST**          | Databricks workspace URL                                 | `https://dbc-a1b2345c-d6e7.cloud.databricks.com` |
| **DATABRICKS\_TOKEN**         | Personal access token for a workspace user               | —                                                |
| **DATABRICKS\_WAREHOUSE\_ID** | Optional SQL warehouse ID; required only for SQL queries | —                                                |

## Required permissions

The connection acts as the user who created the token, so scope that user deliberately.

<Tip>
  Create the token as a user with read access to the clusters, jobs, and catalog assets agents should investigate — not a workspace admin. Leave **DATABRICKS\_WAREHOUSE\_ID** empty if you do not want agents running SQL.
</Tip>

## Agent capabilities

Once connected, agents can:

| Capability                   | Description                                                   |
| ---------------------------- | ------------------------------------------------------------- |
| **Cluster and job review**   | Review clusters, jobs, and run history                        |
| **Failure diagnosis**        | Investigate failed runs and explain what went wrong           |
| **Notebook and file review** | Read notebooks and workspace files for context                |
| **Catalog exploration**      | Explore catalog assets and their metadata                     |
| **Focused SQL queries**      | Run bounded data queries through the configured SQL warehouse |

### Verify the connection

```text theme={null}
@tony list my Databricks clusters and jobs and summarize their current state
```

### Example prompts

```text theme={null}
@tony #report the root cause of the last failed run of the nightly-etl job on Databricks
@tony #recommend which of my Databricks clusters look idle or oversized
@tony #report row counts by day for the sales catalog table over the last week
```

## Troubleshooting

<Accordion title="401 or 403 Unauthorized">
  The token is wrong, expired, or was revoked — Databricks revokes tokens unused for 90 days. Generate a new token and update the connection.
</Accordion>

<Accordion title="Connection cannot reach the workspace">
  **DATABRICKS\_HOST** is wrong or unreachable. Use the full workspace URL, including `https://`, exactly as it appears in your browser.
</Accordion>

<Accordion title="SQL queries fail while everything else works">
  **DATABRICKS\_WAREHOUSE\_ID** is missing or wrong, or the warehouse is stopped. Copy the ID from the warehouse's **Connection details** and confirm the warehouse can start.
</Accordion>

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Token identity** — the connection can do whatever the token's user can do, so create it from a deliberately scoped user.
- **Opt in to SQL** — leaving the warehouse ID empty keeps the connection to cluster, job, and catalog review.

## Related

<CardGroup cols={2}>
  <Card title="Snowflake Connection" icon="https://mintcdn.com/cloudthinker/fJM2cOggET3WD6Z_/images/icons/snowflake.svg?fit=max&auto=format&n=fJM2cOggET3WD6Z_&q=85&s=15d4884d6934b4b7c0143d7e80f8fd6b" href="/guide/connections/snowflake" width="64" height="64" data-path="images/icons/snowflake.svg">
    Warehouse cost and query analysis
  </Card>

  <Card title="Tony Agent" icon="database" href="/guide/agents/tony">
    Database analysis and optimization
  </Card>
</CardGroup>