Skip to main content
Connect your Databricks SQL warehouse to Draftt to govern the assets you track there. Draftt authenticates as a dedicated service principal with read-only access and only reads the schema or tables you grant.
Draftt’s access is read-only. The connector only ever receives USE CATALOG, USE SCHEMA, and SELECT — it can never write, modify, or delete data. Your secret is encrypted at rest and never shown again after you save.

​
What you’ll need

  • Databricks account admin — to create the service principal (in the account console) and assign it to your workspace.
  • Metastore admin, or the owner of the target schema and tables — to grant the service principal read access to your data.
  • A SQL warehouse (serverless or pro). A serverless warehouse doesn’t need to be running — it starts on demand.
  • Access to the Draftt dashboard (Integrations > Azure Databricks > Add), with the Developer role or higher.
The Draftt wizard has three steps — Connect, Permissions, and Review — and generates ready-to-run GRANT statements for you along the way.

​
Step 1 — Connect

Give the connection a name (for example Analytics warehouse -- prod), then choose how Draftt authenticates. OAuth M2M is recommended for production; a personal access token (PAT) is supported as a legacy alternative.
Use this when the service principal and its secret are managed by Databricks.
1

Create the service principal (account console)

In the Databricks account console go to User management > Service principals > Add service principal, type a name (for example draftt-connector), and pick Create new service principal.
2

Assign it to your workspace

In your workspace, go to Settings > Identity and access > Service principals > Manage > Add service principal and select the principal you just created. Then open it and explicitly enable the Databricks SQL access entitlement (don’t rely on the users-group default).
3

Generate an OAuth secret

Under Settings > Identity and access > Service principals > (your principal) > Secrets > Generate secret, set the secret’s lifetime (max 730 days) and copy the Secret and Client ID now — the secret is shown only once. The Client ID is the service principal’s application ID.
Draftt can’t renew the secret automatically — note when it expires.
4

Grant warehouse access

Grant the principal Can use on your SQL warehouse: SQL Warehouses > (your warehouse) > Permissions (also available from the kebab menu on the warehouse list).
5

Test the connection in Draftt

Enter the Workspace host (host only, no https://, e.g. adb-1234567890123456.7.azuredatabricks.net), the Client ID, and the OAuth secret, keep Where was this service principal created? on Databricks-managed, and click Test connection. The button shows Connected on success.

​
Step 2 — Permissions

The Permissions step walks through four numbered sections; each unlocks when the previous one completes.
1

Select a SQL warehouse

Pick the warehouse Draftt should query. The list only shows warehouses the connecting principal can use — if it’s empty, grant the principal Can use on a warehouse (or create one), then refresh.
2

Open the path to the data

Enter the catalog and schema that hold your inventory. The wizard generates the exact grants with your principal filled in — run them in a Databricks SQL editor, then click Verify access:
<client-id> is the service principal’s application (client) ID — a GUID, not its display name. Copy the statements from the wizard to get them pre-filled.
3

Grant read access

By default Draftt asks for schema-wide read access, which covers every current and future table in the schema:
To restrict access, toggle Limit to specific tables and grant table-by-table instead:
4

Validate access

Click Check access. Draftt confirms it can actually read what you granted (for schema-wide access it samples a few tables; for specific tables it probes each one). You can’t continue until validation passes.

​
Step 3 — Review and save

The Review step summarizes the workspace host, warehouse, access mode, and the tables to sync. Click Save Connection — Draftt re-validates the credentials server-side before storing them (encrypted at rest). If the name is already taken you’ll get an inline error; pick another name.

​
What Draftt reads

Draftt’s access is SELECT-only, limited to the catalog, schema, and tables you granted. During setup and validation it runs only:
  • SELECT 1 — connection probe
  • SHOW TABLES IN <catalog>.<schema> — table discovery
  • DESCRIBE TABLE — column metadata
  • SELECT * FROM <table> LIMIT 1 — a one-row readability probe
It cannot create, modify, or delete anything, and it never reads data outside the granted schema or tables.

​
Troubleshooting

Authentication failed: Check the client ID and OAuth secret (or PAT) and confirm the secret hasn’t expired. The error notes whether the rejection came from Microsoft Entra ID or from Databricks — if a secret issued in the Azure portal is rejected with a 401, make sure Microsoft Entra ID app is selected on the Connect step. Cannot access the SQL warehouse: Verify the warehouse exists and the connecting principal has Can use on it. For Entra ID principals, also confirm the principal was added to the Databricks account and assigned to the workspace with the Databricks SQL access entitlement. No SQL warehouses listed: The list only shows warehouses the principal can use. Grant Can use on an existing warehouse, or create a serverless or pro warehouse, then refresh. Missing Unity Catalog permissions: Grant USE CATALOG, USE SCHEMA, and SELECT on the target catalog, schema, and tables — to the principal’s application ID, not its display name. Catalog, schema, or table not found: The selected object may have been renamed or dropped, or the name is misspelled. Verify it exists in Catalog Explorer. Warehouse is stopped or starting: Wait for it to start (serverless warehouses start on demand) and retry. Could not reach the workspace: Check the workspace host value and the warehouse HTTP path. Unexpected error: Try again; if it persists, contact Draftt support.