> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Databricks Lakebase

> Build apps with read and write access to a Databricks Lakebase database

export const IntegrationSuccess = ({integrationName}) => {
  return <p>
      <b>{integrationName} connected!</b><br />You can now use{" "}
      <a href="/building-with-clark">Clark to build</a> with {integrationName}.
    </p>;
};

export const Alert = ({type, title, children}) => {
  const getIcon = () => {
    switch (type) {
      case 'info':
        return "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 20 20' fill='none'%3E%3Cpath d='M10 0C4.477 0 0 4.477 0 10s4.477 10 10 10 10-4.477 10-10S15.523 0 10 0zm0 15c-.552 0-1-.448-1-1s.448-1 1-1 1 .448 1 1-.448 1-1 1zm1-3H9V6h2v6z' fill='%230099FF'/%3E%3C/svg%3E";
      case 'success':
        return "data:image/svg+xml,%3Csvg width='20' height='20' viewBox='0 0 20 20' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill-rule='evenodd' clip-rule='evenodd' d='M10 0C4.477 0 0 4.477 0 10s4.477 10 10 10 10-4.477 10-10S15.523 0 10 0zm4.293 6.293L9 11.586 5.707 8.293c-.391-.391-1.024-.391-1.414 0s-.391 1.024 0 1.414l4 4c.391.391 1.024.391 1.414 0l6-6c.391-.391.391-1.024 0-1.414s-1.024-.391-1.414 0z' fill='%230CC26D'/%3E%3C/svg%3E";
      case 'warning':
        return "data:image/svg+xml;charset=utf-8;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHhtbDpzcGFjZT0ncHJlc2VydmUnIHdpZHRoPScxMDgwJyBoZWlnaHQ9JzEwODAnPjxyZWN0IHdpZHRoPScxMDAlJyBoZWlnaHQ9JzEwMCUnIGZpbGw9J3RyYW5zcGFyZW50Jy8+PHBhdGggZD0nTTEzLjc5NCAxMC43NSA4LjMgMS4yNWExLjUgMS41IDAgMCAwLTIuNiAwbC01LjQ5NCA5LjVBMS40OTQgMS40OTQgMCAwIDAgMS41IDEzaDExYTEuNDkzIDEuNDkzIDAgMCAwIDEuMjk0LTIuMjVNNi41IDUuNWEuNS41IDAgMCAxIDEgMFY4YS41LjUgMCAwIDEtMSAwek03IDExYS43NS43NSAwIDEgMSAwLTEuNS43NS43NSAwIDAgMSAwIDEuNScgc3R5bGU9J3N0cm9rZTpub25lO3N0cm9rZS13aWR0aDoxO3N0cm9rZS1kYXNoYXJyYXk6bm9uZTtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS1kYXNob2Zmc2V0OjA7c3Ryb2tlLWxpbmVqb2luOm1pdGVyO3N0cm9rZS1taXRlcmxpbWl0OjQ7ZmlsbDojZmY5ZjM1O2ZpbGwtcnVsZTpub256ZXJvO29wYWNpdHk6MScgdHJhbnNmb3JtPSd0cmFuc2xhdGUoLjAyIDE5LjMwNSlzY2FsZSg3Ny4xNCknLz48L3N2Zz4=";
      case 'danger':
        return "data:image/svg+xml,%3Csvg width='20' height='20' viewBox='0 0 20 20' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M10 0C4.477 0 0 4.477 0 10s4.477 10 10 10 10-4.477 10-10S15.523 0 10 0zm5.707 4.293L10 9.586 4.293 4.293c-.391-.391-1.024-.391-1.414 0s-.391 1.024 0 1.414L8.586 11l-5.707 5.293c-.391.391-.391 1.024 0 1.414s1.024.391 1.414 0L10 12.414l5.707 5.293c.391.391 1.024.391 1.414 0s.391-1.024 0-1.414L11.414 11l5.707-5.293c.391-.391.391-1.024 0-1.414s-1.024-.391-1.414 0z' fill='%23F45252'/%3E%3C/svg%3E";
      case 'note':
        return "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 20 20' fill='none'%3E%3Cpath d='M10 0C4.477 0 0 4.477 0 10s4.477 10 10 10 10-4.477 10-10S15.523 0 10 0zm0 15c-.552 0-1-.448-1-1s.448-1 1-1 1 .448 1 1-.448 1-1 1zm1-3H9V6h2v6z' fill='%230099FF'/%3E%3C/svg%3E";
      default:
        return "";
    }
  };
  return <div className={`alert alert--${type}`}>
      <div className="alert-icon" style={{
    backgroundImage: `url("${getIcon()}")`,
    backgroundRepeat: 'no-repeat',
    backgroundPosition: 'center center',
    backgroundSize: '20px',
    width: '24px',
    height: '24px',
    position: 'absolute',
    left: '16px',
    top: '16px'
  }} />
      <div className="alert-content">
        {title && <div className="alert-title">{title}</div>}
        <div className="alert-body">{children}</div>
      </div>
    </div>;
};

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

<Alert type="info">
  <p>
    If you're using Superblocks Cloud, you may need to allowlist Superblocks IP addresses to connect to your database.
    Learn how to configure this in Databrick's guide on{" "}
    <a href="https://docs.databricks.com/aws/en/security/network/front-end/ip-access-list-workspace">Configuring IP access lists</a>.
    Alternatively, use the Superblocks Hybrid or Cloud-Prem architectures to keep your data within your VPC.
  </p>
</Alert>

### 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)](https://docs.databricks.com/aws/en/dev-tools/auth/pat)         | Use a short or long-lived access token for a user or service principal.                                                                                             |
| [Machine-to-machine OAuth](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m)      | 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](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-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

1. In the web app, navigate to the{" "}
   <a href="https://app.superblocks.com/integrations">Integrations</a> page
2. Click <strong>Add integration</strong>
3. Search for <strong>Databricks Lakebase</strong> and select it from the list of available integrations
4. <strong>Name</strong> the integration
5. Fill out the integration configuration as follows:

<Tabs>
  <Tab title="Personal access token">
    | Field                             | Required                                   | Description                                                                                       |
    | --------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------- |
    | Host                              | <span className="table-checkmark">✓</span> | Databricks Lakebase host name (e.g. `xxxx.cloud.databricks.com`)                                  |
    | Port                              | <span className="table-checkmark">✓</span> | Port to use when connecting (default: `5432`)                                                     |
    | Database Name                     | <span className="table-checkmark">✓</span> | Name of database to connect to                                                                    |
    | Default schema                    | <span className="table-x">✗</span>         | An optional initial schema to use                                                                 |
    | Database Username                 | <span className="table-checkmark">✓</span> | Username to use to connect                                                                        |
    | Access token                      | <span className="table-checkmark">✓</span> | Databricks personal access token                                                                  |
    | Enable SSL                        | <span className="table-x">✗</span>         | Connect using SSL                                                                                 |
    | Use a self-signed SSL certificate | <span className="table-x">✗</span>         | Provide <strong>Server CA</strong>, <strong>Client Key</strong>, and <strong>Client Cert</strong> |
  </Tab>

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

  <Tab title="OAuth token federation">
    | Field                             | Required                                   | Description                                                                                                                                                                                                                                                                                                                         |
    | --------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Host                              | <span className="table-checkmark">✓</span> | Databricks Lakebase host name (e.g. `xxxx.cloud.databricks.com`)                                                                                                                                                                                                                                                                    |
    | Port                              | <span className="table-checkmark">✓</span> | Port to use when connecting (default: `5432`)                                                                                                                                                                                                                                                                                       |
    | Database Name                     | <span className="table-checkmark">✓</span> | Name of database to connect to                                                                                                                                                                                                                                                                                                      |
    | Default schema                    | <span className="table-x">✗</span>         | An optional initial schema to use                                                                                                                                                                                                                                                                                                   |
    | Database Username                 | <span className="table-checkmark">✓</span> | Username to use to connect                                                                                                                                                                                                                                                                                                          |
    | Subject token source              | <span className="table-checkmark">✓</span> | 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                         | <span className="table-checkmark">✓</span> | Databricks token URL. Choose a URL format based on the federation policy you previously configured.<br /><br />**Workspace identity federation**<br />`https://<databricks-workspace-host>/oidc/v1/token`<br /><br />**Account-wide token federation**<br />`https://<databricks-account-host>/oidc/accounts/<account-id>/v1/token` |
    | Service Principal UUID            | <span className="table-x">✗</span>         | Only required if using [Workload identity federation](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation-policy). The service principal client ID to authenticate as.                                                                                                                                               |
    | Enable SSL                        | <span className="table-x">✗</span>         | Connect using SSL                                                                                                                                                                                                                                                                                                                   |
    | Use a self-signed SSL certificate | <span className="table-x">✗</span>         | Provide <strong>Server CA</strong>, <strong>Client Key</strong>, and <strong>Client Cert</strong>                                                                                                                                                                                                                                   |

    <Alert type="warning">
      <p>
        <strong>Login identity provider</strong> token source is only supported for Enterprise organizations with OIDC-based <a href="/admin/org-administration/auth/single-sign-on">Single Sign-On</a> configured. If you're not sure how your SSO provider is configured, contact support for assistance.
      </p>
    </Alert>
  </Tab>
</Tabs>

6. Optionally, add more configurations to set credentials for [different environments](/development-lifecycle/build/data-tags)
7. Click <strong>Test Connection</strong> to check that Superblocks can connect to the data source
8. Click <strong>Create</strong>

<Alert type="success">
  <IntegrationSuccess integrationName="Databricks Lakebase" />
</Alert>

## 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](/integrations/troubleshooting/troubleshooting-databases).

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**<br />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.<br /><br />**Resolution**<br />Reach out to <a href="mailto:support@superblocks.com">[support@superblocks.com](mailto:support@superblocks.com)</a> for assistance configuring SSO or migrating your SSO configuration to OIDC.                                                                                                                                                                                                                                                                                                                                                               |
| `Failed to process token: TOKEN_EXPIRED`                                                               | **Reason**<br />The access token issued to Superblocks when you logged in, or the static token you've provided has expired.<br /><br />**Resolution**<br />If using **Logged in 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**<br />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.<br /><br />**Resolution**<br />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 <a href="mailto:support@superblocks.com">[support@superblocks.com](mailto:support@superblocks.com)</a>