Databricks SQL

Covers a Databricks SQL warehouse over Unity Catalog, on AWS, Azure or Google Cloud. The gateway signs in as a service principal with an OAuth secret, or with a personal access token.

Before you start

• A workspace with Unity Catalog and a SQL warehouse.
• A workspace admin, to make the service principal and grant it access.
• The workspace host, such as dbc-1234abcd-5678.cloud.databricks.com, on the gateway’s allowed hosts, listed by its exact name (Allow the host).

Network access

The gateway connects to the workspace over HTTPS. If the workspace has an IP access list, add the gateway’s outbound address to it (Network access says which address that is).

Create a read-only login

1. In the workspace, open Settings, then Identity and access, then Service principals, and add one named portward-reader. Copy its Application ID.
2. On the service principal’s Secrets tab, generate a secret. Copy the secret; Databricks shows it once.
3. On the SQL warehouse’s Permissions, give portward-reader Can use.
4. In the SQL editor, run this. Replace main and main.sales with your catalog and schema, and <application id> with the ID from step 1.

GRANT USE CATALOG ON CATALOG main TO `<application id>`;
GRANT USE SCHEMA, SELECT ON SCHEMA main.sales TO `<application id>`;

Grant nothing else. Setup refuses the service principal if it owns the catalog or schema, or holds ALL PRIVILEGES, MANAGE, MODIFY or any CREATE privilege on them. Don’t add it to the workspace’s admins group.

Connect it in setup

Choose Databricks SQL and fill in Name (the name people and the AI see, such as sales), Workspace host and HTTP path (both from the SQL warehouse’s Connection details), Catalog, Schema and Sign-in. For Service principal (OAuth), give the Client id (the Application ID) and the secret. For a personal access token, leave Client id empty and paste the token. Use the OAuth secret if you can. The tokens it gets expire after an hour.

What the setup check tests

Before it saves, setup connects and checks, in this order:

1. The workspace host is on the allowed hosts, listed by its exact name (“is on a domain other customers share”), and the HTTP path looks like /sql/1.0/warehouses/<id>.
2. It can sign in. A wrong client id or secret gets “Databricks refused the service principal’s client id or secret”.
3. The principal is not a workspace admin (“connect with a read-only principal, not a workspace admin”).
4. A token computed inside Databricks matches the gateway’s own (“in-database tokens don’t match Python”).
5. It can see its metastore (“the principal can’t see its metastore”), and is not a metastore admin (“the principal is a metastore admin; use a read-only principal”).
6. The catalog and schema exist (“catalog or schema not found (or not granted)”), the principal owns neither (“the principal owns the”), and holds no write or CREATE privilege on them (“on the catalog or schema; use a read-only principal”).
7. It lists the schema’s tables. A table the principal owns or could MODIFY is listed as one it could change, and can’t be exposed.

Databricks SQL has no read-only transaction, so these grants are what stops a write. The gateway also accepts nothing but a single SELECT from the AI.