# Connect to Databricks

> What your Databricks admin sets up, how you sign in, how live queries work, what the semantic layer switch reads, and how to fix the errors you're most likely to hit.

Connect · 10 min read · Updated 2026-11-05

### Before you start

Use **Sign in with Databricks**: it's Databricks' recommended method, and each person queries with their own Unity Catalog permissions.

You'll need:

- A Databricks workspace with Unity Catalog enabled.
- A SQL warehouse. We recommend serverless: it starts in seconds, so your first query doesn't wait on a cold cluster.
- Your workspace's **server hostname**, for example `dbc-1234abcd.cloud.databricks.com` or `adb-1234567890.1.azuredatabricks.net`.
- For OAuth only: a Databricks **account admin** for a one-time, 2-minute app registration.

| Method | Who it signs in as | Setup | Pick it when |
| --- | --- | --- | --- |
| Sign in with Databricks (OAuth) | Each Golden user, as themselves | Account admin registers an app once; each user signs in | You want per-user permissions, row filters and column masks. Recommended. |
| Authenticate with Google | The person who authorized it, shared | A federation policy that trusts Google | Your team signs in to Databricks with Google. |
| Personal access token (legacy) | The token's owner, shared | Paste a token | A quick trial. Databricks recommends OAuth over tokens. |

### Privileges Golden needs

Golden only reads. A non-admin user needs 4 grants, and nothing else:

| Grant | On | Why |
| --- | --- | --- |
| `CAN USE` | The SQL warehouse | Run queries |
| `USE CATALOG` | Each catalog you'll analyze | See the catalog |
| `USE SCHEMA` | Each schema you'll analyze | See its tables |
| `SELECT` | The tables and views you'll analyze (or the schema) | Read the rows |

A Unity Catalog admin can grant the last 3 in SQL. Grant to a group rather than to each person:

```sql
GRANT USE CATALOG ON CATALOG sales TO `golden-analysts`;
GRANT USE SCHEMA ON SCHEMA sales.reporting TO `golden-analysts`;
GRANT SELECT ON SCHEMA sales.reporting TO `golden-analysts`;
```

With OAuth, these are each person's own grants, so Golden shows every user exactly what Databricks lets them see. With a token or Google, everyone in Golden sees what the connection's owner can see.

### Set up Sign in with Databricks (recommended)

An account admin registers Golden once; after that, each person connects in one click. Golden uses a public OAuth client with PKCE, so no secret is ever stored.

**In Golden:**

1. Go to **Data → Add connection → Databricks**. *Sign in with Databricks* is preselected.
2. Enter your **server hostname** and, optionally, a name like *Production Databricks*.
3. Copy the **redirect URL** Golden shows you.

**In the Databricks account console** (a Databricks account admin; this lives in the account console, not a workspace setting):

1. Open **Settings → App connections → Add connection**.
2. Paste Golden's redirect URL.
3. Select the **SQL** access scope.
4. **Uncheck "Generate a secret."** Golden signs in with PKCE and needs no secret.
5. Save, then copy the **Client ID**.

**Back in Golden:**

1. Paste the Client ID and save.
2. Click **Connect your account** and sign in to Databricks in the popup. Golden shows *Connected as* your name.
3. Create a dataset and pick the SQL warehouse, catalog and schema to query.

Everyone else on your team just opens the connection and clicks **Connect your account**. Golden refreshes each person's token in the background, so nobody gets signed out mid-analysis.

### Set up Authenticate with Google

If your team signs in to Databricks with Google, Golden can trade a Google sign-in for a Databricks token. The connection is shared: everyone in Golden queries as the person who authorized it.

**In the Databricks account console** (account admin, once):

1. Open **Settings → Security → Federation policies** and create an account-wide policy.
2. Set the issuer to `https://accounts.google.com`.
3. Set the audience to Golden's Google client ID: `[GOLDEN_GOOGLE_CLIENT_ID]`.
4. Set the subject claim to `email`, so the Google address maps to the matching Databricks user.

**In Golden:**

1. Go to **Data → Add connection → Databricks** and choose **Authenticate with Google**.
2. Enter the **server hostname** and **HTTP path** (in Databricks: **SQL Warehouses → your warehouse → Connection details**).
3. Click **Authenticate with Google**, sign in, and save.

The person who authorizes needs the grants in *Privileges Golden needs*. If their Google access is revoked, Golden asks them to reconnect.

### Set up a personal access token (legacy)

Tokens still work and take about 30 seconds, but Databricks recommends OAuth. Everyone in Golden queries as the token's owner.

1. In Databricks, open **your profile → Settings → Developer → Access tokens → Generate new token**. Give it a lifetime your security team accepts.
2. Copy the **server hostname** and **HTTP path** from **SQL Warehouses → your warehouse → Connection details**.
3. In Golden, go to **Data → Add connection → Databricks** and choose **Personal access token (legacy)**.
4. Paste the hostname, HTTP path and token. Optionally set a default catalog and schema.
5. Save. Golden tests the connection before it stores anything.

Golden encrypts the token at rest. Better still, create it for a service principal with only the grants above, so the connection doesn't break when someone leaves.

### Troubleshooting and disconnecting

| What you see | Likely cause | Fix |
| --- | --- | --- |
| Databricks rejects the redirect during sign-in | The redirect URL in the app connection doesn't match Golden's exactly | Copy it from Golden again and paste it into the app connection |
| Sign-in fails with an invalid client error | A secret was generated, or the Client ID was mistyped | Re-create the app connection with "Generate a secret" unchecked |
| A table is missing from the list | No `USE SCHEMA` or `SELECT` on it | Ask your Unity Catalog admin for the grants above |
| The first query is slow or times out | A classic warehouse is starting up | Retry in a minute, or switch to a serverless warehouse |
| Golden asks you to reconnect | Your token or Google grant was revoked or expired | Click **Reconnect** and sign in again |

**Find Golden's queries:** in Databricks **Query History**, the **Source** column reads `GoldenAnalytics_Golden`.

**Disconnect:** remove the connection in Golden. For OAuth, an account admin can also delete Golden's app connection in the account console, which signs every user out at once. For a token, revoke it under **Access tokens**.

### Notes for reviewers (delete before publishing)

The steps are written from the code on `main` plus PRs #4288 and #4290. Resolve these before it goes to customers:

- [ ] Fill in `[GOLDEN_GOOGLE_CLIENT_ID]`. The value is the `GOOGLE_CLIENT_ID` env var, which isn't in the repo.
- [ ] Confirm the Databricks console labels (App connections, Federation policies, Access tokens) against a live account; Databricks renames them often.
- [ ] Publish only after #4290 merges, or the "preselected" line in step 1 is wrong. Same for #4288 and the Query History line.
- [ ] OAuth is behind the `DatabricksOauthV1Feature` flag. Customers without it won't see *Sign in with Databricks* until the flag is on for everyone.
- [ ] The Google exchange asks Databricks for the `all-apis` scope. The partner framework asks for least-privilege scopes, so consider narrowing it to `sql`.
- [ ] Databricks' validation wants this as live documentation; publish it through the in-app help editor and link it from the partner submission.

Source: https://goldenanalytics.com/docs/imported-mvd7h7iz