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: Target catalog in your Databricks workspace.
  • Schema: Default schema to connect to.
  • 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: Found in your Databricks Data Explorer or Unity Catalog
  • Schema: The specific schema/database you want to query by default

​
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 target catalog/schema
Timeout Issues
  • Ensure your SQL warehouse is running (not stopped)
  • Check if your warehouse has auto-stop enabled and restart if needed

​
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
  • Use catalog and schema specification to limit data access scope