Skip to main content

​
Prerequisites

Before starting, make sure you have:
  • Access to a Databricks workspace
  • Permission to use a SQL Warehouse
  • Access to Unity Catalog resources (catalogs, schemas, tables) that you want Sidecar to discover
  • Unity Catalog admin access (or help from someone who has it) to grant privileges to the Sidecar service principal

​
1. Get the Host and HTTP Path

  1. Log in to your Databricks workspace.
  2. Navigate to SQL Warehouses.
  3. Select the SQL Warehouse you want to use for the integration.
  4. Click Connection details.
Copy the following values: Server Hostname — use this as the Host: 
dbc-xxxxxxxx.cloud.databricks.com
HTTP Path — use this as the HTTP Path: 
/sql/1.0/warehouses/xxxxxxxxxxxx

​
2. Create a Service Principal and OAuth Secret

  1. Click your username in the top bar and select Settings.
  2. Click the Identity and access tab.
  3. Next to Service principals, click Manage.
  4. Create a new service principal for Sidecar.
  5. Click the created service principal, then click the Secrets tab.
  6. Click Generate secret.
  7. Set the secret’s lifetime in days (maximum 730 days).
  8. Click Generate.
  9. Copy the displayed secret and client ID, then click Done.
The secret is shown only once. The client ID is the same as the service principal’s application ID.

​
3. Grant permissions

Grant your Sidecar service principal (the OAuth identity from step 2) the following before you test or save the integration in Sidecar.
  • SQL warehouse: In SQL Warehouses → your warehouse → Permissions, add the service principal with Can use.
  • Data you want Sidecar to scan: For each Unity Catalog Sidecar should discover besides system, rerun the next section’s three GRANT statements, replacing system with that catalog’s name and <principal> with your Sidecar service principal (usually a catalog owner or metastore admin runs them). If catalog-wide SELECT is not allowed, grant USE SCHEMA and SELECT only on the schemas and objects Sidecar needs.
  • system catalog: Sidecar reads tables in the system catalog for query history, lineage, and billing. Grant catalog-wide access on system so the principal can use all schemas and SELECT from all tables and views there. In a workspace SQL editor, run—replace <principal> with your Sidecar service principal’s Unity Catalog identity: 
-- Allow the principal to see the catalog
GRANT USE CATALOG ON CATALOG system TO `<principal>`;

-- Allow the principal to see all schemas within the catalog
GRANT USE SCHEMA ON CATALOG system TO `<principal>`;

-- Allow the principal to select from all tables/views in the catalog
GRANT SELECT ON CATALOG system TO `<principal>`;

​
4. Configure the Integration

Enter the following information in the Sidecar integration setup page:
FieldDescription
HostDatabricks Server Hostname
HTTP PathSQL Warehouse HTTP Path
Client IDClient ID of OAuth Secret
Client SecretSecret of OAuth Secret
After entering the credentials:
  1. Click Test Connection.
  2. Click Save to finish the integration.

​
Result

After the integration is complete, Sidecar will be able to:
  • Connect to your Databricks SQL Warehouse
  • Discover catalogs, schemas, and tables
  • Query metadata from Unity Catalog
  • Use system catalog data for query history, lineage, and billing when those grants are in place