Connect to Databricks

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.

Privileges Golden needs

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

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

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. 1Go to Data → Add connection → Databricks. Sign in with Databricks is preselected.
2. 2Enter your server hostname and, optionally, a name like Production Databricks.
3. 3Copy 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. 1Open Settings → App connections → Add connection.
2. 2Paste Golden's redirect URL.
3. 3Select the SQL access scope.
4. 4Uncheck "Generate a secret." Golden signs in with PKCE and needs no secret.
5. 5Save, then copy the Client ID.

Back in Golden:

1. 1Paste the Client ID and save.
2. 2Click Connect your account and sign in to Databricks in the popup. Golden shows Connected as your name.
3. 3Create 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. 1Open Settings → Security → Federation policies and create an account-wide policy.
2. 2Set the issuer to https://accounts.google.com.
3. 3Set the audience to Golden's Google client ID: [GOLDEN_GOOGLE_CLIENT_ID].
4. 4Set the subject claim to email, so the Google address maps to the matching Databricks user.

In Golden:

1. 1Go to Data → Add connection → Databricks and choose Authenticate with Google.
2. 2Enter the server hostname and HTTP path (in Databricks: SQL Warehouses → your warehouse → Connection details).
3. 3Click 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. 1In Databricks, open your profile → Settings → Developer → Access tokens → Generate new token. Give it a lifetime your security team accepts.
2. 2Copy the server hostname and HTTP path from SQL Warehouses → your warehouse → Connection details.
3. 3In Golden, go to Data → Add connection → Databricks and choose Personal access token (legacy).
4. 4Paste the hostname, HTTP path and token. Optionally set a default catalog and schema.
5. 5Save. 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

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.