Skip to main content
This guide walks you through connecting your Databricks warehouse to TextQL, enabling you to query your Databricks data using Ana, our SQL chatbot.

​
Prerequisites

Before setting up the connector in TextQL, you’ll need to prepare your Databricks environment:

​
1. Create a SQL Warehouse in Databricks

  1. Log into your Databricks workspace
  2. Navigate to SQL Warehouses in the sidebar
  3. Click Create SQL Warehouse
  4. Configure your warehouse settings (size, auto-stop, etc.)
  5. Start the warehouse and note the Server Hostname and HTTP Path

​
2. Generate a Personal Access Token (PAT)

  1. In Databricks, click your profile icon in the top-right corner
  2. Select User Settings
  3. Go to the Access tokens tab
  4. Click Generate new token
  5. Set an appropriate comment and expiration time
  6. Copy and securely store the generated token

​
Creating the Connector in TextQL

Navigate to the TextQL Connectors Page and click Create New Connector. Select Databricks from the available connectors to open the configuration form.

​
Connection Details

The form requires the following information:
  • Connector Name: A descriptive name to identify this specific Databricks connection in TextQL.
  • Host: Your Databricks workspace hostname (without https://).
  • Port: Connection port (typically 443 for HTTPS).
  • HTTP Path: SQL warehouse HTTP path from Databricks.
  • Catalog (optional): Catalog to start in. Leave blank and TextQL browses every Unity Catalog catalog your credentials can access.
  • Schema (optional): Schema to start in. Leave blank and TextQL browses every schema in the catalog.
  • Personal Access Token: The PAT you generated in Databricks (will be masked).

​
Finding Your Connection Details

Server Hostname and HTTP Path:
  1. In Databricks, go to SQL Warehouses
  2. Click on your warehouse name
  3. Go to the Connection details tab
  4. Copy the Server hostname and HTTP path
Catalog and Schema Information:
  • Catalog (optional): Found in your Databricks Data Explorer or Unity Catalog. When set, the session starts in this catalog, so unqualified table names resolve there. When blank, discovery covers every catalog the credentials can access, falling back to the workspace’s default catalog if Unity Catalog system tables are unavailable.
  • Schema (optional): When set, the session starts in this schema. When blank, discovery covers every schema in the catalog.
These fields guide discovery and set defaults only. Access is still governed by Databricks permissions and Unity Catalog grants.

​
Testing the Connection

After entering your credentials, click Test Connection to verify your settings. If the test passes, click Create Connector to establish the connection.

​
Troubleshooting

​
Common Connection Issues

“Failed to create connection: databricks: request error: invalid DSN: invalid DSN port”
  • Verify the port is set to 443 (not empty or other values)
  • Ensure the hostname doesn’t include https:// prefix
Authentication Errors
  • Verify your Personal Access Token is valid and hasn’t expired
  • Check that the token has appropriate permissions for the catalogs and schemas you need
  • Using a service principal (client credentials)? Its OAuth secret needs the sql scope. Older TextQL versions request all-apis, so a secret scoped to sql only fails there with “Scopes ‘all-apis’ are not assigned to the client”. Add all-apis to the secret, or upgrade TextQL.
Timeout Issues
  • Ensure your SQL warehouse is running (not stopped)
  • Check if your warehouse has auto-stop enabled and restart if needed
Having trouble connecting? See the Network Configuration Guide for firewall and IP whitelisting setup.

​
Best Practices

  • Warehouse Management: Use appropriately sized warehouses for your query workload
  • Security: Regularly rotate your Personal Access Tokens
  • Performance: Consider using larger warehouses for complex analytical queries
  • Cost: Enable auto-stop on warehouses to manage costs

​
Next Steps

Once connected, you can use TextQL to query your Databricks data. The connector automatically handles session management and warehouse connections. For optimal performance:
  • Configure an appropriate warehouse size for your workload
  • Set up proper access controls in your Databricks workspace
  • Set a catalog and schema so unqualified table names resolve to them