Databricks Lakebase - Superblocks Docs

Databricks Lakebase is a fully managed Postgres database integrated with the Databricks lakehouse, built for modern operational workloads. It provides a Postgres-compatible OLTP database that eliminates complex ETL pipelines and ensures transactional data is seamlessly integrated with analytics and AI-driven applications. Integrate Databricks Lakebase with Superblocks to build internal tools and workflows that query, analyze, and update your data using familiar PostgreSQL syntax.

Setting up Databricks Lakebase

Configure authentication

To access your Databricks Lakebase database, you’ll need to authenticate using a Databricks account. Superblocks provides several different ways to authenticate. See the Databricks documentation below for how to configure your preferred authentication method.

Method	Description
Personal access token (PAT)	Use a short or long-lived access token for a user or service principal.
Machine-to-machine OAuth	Configure OAuth client credentials for a service principal. Superblocks will exchange the client credentials with Databricks to retrieve a short-lived OAuth token.
OAuth token federation	Use OAuth tokens issued by your identity provider when users log in to Superblocks to authenticate with Databricks using the authenticated user’s permissions.

Add integration

In the web app, navigate to the Integrations page
Click Add integration
Search for Databricks Lakebase and select it from the list of available integrations
Name the integration
Fill out the integration configuration as follows:

Personal access token
Machine-to-machine OAuth
OAuth token federation

Field	Required	Description
Host	✓	Databricks Lakebase host name (e.g. `xxxx.cloud.databricks.com`)
Port	✓	Port to use when connecting (default: `5432`)
Database Name	✓	Name of database to connect to
Default schema	✗	An optional initial schema to use
Database Username	✓	Username to use to connect
Access token	✓	Databricks personal access token
Enable SSL	✗	Connect using SSL
Use a self-signed SSL certificate	✗	Provide Server CA, Client Key, and Client Cert

Field	Required	Description
Host	✓	Databricks Lakebase host name (e.g. `xxxx.cloud.databricks.com`)
Port	✓	Port to use when connecting (default: `5432`)
Database Name	✓	Name of database to connect to
Default schema	✗	An optional initial schema to use
Database Username	✓	Username to use to connect
OAuth client ID	✓	Client ID associated with your service principal
OAuth client secret	✓	Client secret associated with your service principal
Enable SSL	✗	Connect using SSL
Use a self-signed SSL certificate	✗	Provide Server CA, Client Key, and Client Cert

Field	Required	Description
Host	✓	Databricks Lakebase host name (e.g. `xxxx.cloud.databricks.com`)
Port	✓	Port to use when connecting (default: `5432`)
Database Name	✓	Name of database to connect to
Default schema	✗	An optional initial schema to use
Database Username	✓	Username to use to connect
Subject token source	✓	Select Login identity provider to use the access token issued to Superblocks when users log in via SSO, or provide a Static token.
Token URL	✓	Databricks token URL. Choose a URL format based on the federation policy you previously configured. Workspace identity federation `https://<databricks-workspace-host>/oidc/v1/token` Account-wide token federation `https://<databricks-account-host>/oidc/accounts/<account-id>/v1/token`
Service Principal UUID	✗	Only required if using Workload identity federation. The service principal client ID to authenticate as.
Enable SSL	✗	Connect using SSL
Use a self-signed SSL certificate	✗	Provide Server CA, Client Key, and Client Cert

Optionally, add more configurations to set credentials for different environments
Click Test Connection to check that Superblocks can connect to the data source
Click Create

Using Databricks Lakebase in APIs

Once your Databricks Lakebase integration is created, you can start using it by writing SQL in Superblocks APIs. Since Lakebase is fully Postgres-compatible, you can use standard PostgreSQL syntax for all your queries, including support for Postgres extensions like PostGIS and pgvector.

Troubleshooting

If you run into issues, first see our guide on Troubleshooting Database Integrations. There are also several common errors you may see when using Databricks Lakebase. The table below includes error messages, why they happen, and how to address them.

Error message	Why it’s happening & Resolution
`IntegrationOAuthError: OAuth2 - "On-Behalf-Of Token Exchange" could not find identity provider token`	Reason You’ve selected Login identity provider as the subject token source when using OAuth token federation, but you are not currently logged in to Superblocks using an OIDC-based Identity Provider. Resolution Reach out to support@superblocks.com for assistance configuring SSO or migrating your SSO configuration to OIDC.
`Failed to process token: TOKEN_EXPIRED`	Reason The access token issued to Superblocks when you logged in, or the static token you’ve provided has expired. Resolution If using Login identity provider, log out of and back into Superblocks. If using a static token, obtain a new federated JWT from your identity provider.
`Failed to process token: TOKEN_INVALID (Ensure a valid federation policy has been configured)`	Reason Your Databricks account either does not have a federation policy configured, or the `subject_token` being sent to Databricks by Superblocks does not satisfy the policy. This can happen if the token is not a valid JWT, or has a different `aud` or `iss` than configured in the Databricks federation policy. Resolution Make sure the `aud` and `iss` configured in Databricks are the same `aud` and `iss` your IdP uses when issuing tokens to Superblocks. Make sure the Databricks federation policy points to a valid JWKS URI. By default, Databricks uses the URI provided at `<issuer-url>/.well-known/openid-configuration`. You may need to change this if your IdP uses a non-default authorization server or does not support a `/.well-known` discovery URL.

If you are encountering an error that’s not listed, or the provided steps are insufficient to resolve the error, please contact us at support@superblocks.com

​Setting up Databricks Lakebase

​Configure authentication

​Add integration

​Using Databricks Lakebase in APIs

​Troubleshooting

Setting up Databricks Lakebase

Configure authentication

Add integration

Using Databricks Lakebase in APIs

Troubleshooting