> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/SaaS/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/SaaS/configuration/integrations/databricks/databricks-lakebase/register-a-databricks-lakebase-connection.md).

# Register a Databricks Lakebase Connection

Register your Databricks Lakebase data and map your user accounts into Immuta

{% hint style="info" %}
**Public preview**: This integration is available to all accounts that request to enable it for their tenant. Contact your Immuta representative to enable it.
{% endhint %}

## Requirements

* [Databricks Lakebase database](https://docs.databricks.com/aws/en/oltp/instances/about)

## Permissions

The user registering the connection must have the permissions below.

* `APPLICATION_ADMIN` Immuta permission
* The account credentials you provide to register the connection should be a [Databricks service principal](https://docs.databricks.com/aws/en/oltp/instances/manage-privileges#grant-instance-permissions-to-databricks-identities). [Create a PostgreSQL role for the Databricks service principal](https://docs.databricks.com/aws/en/oltp/projects/external-apps-connect#2-create-postgres-role-for-the-service-principal) and [grant it the following permissions](https://docs.databricks.com/aws/en/oltp/projects/manage-roles-permissions) in your Databricks Lakebase database:

  * `databricks_superuser`
  * `CREATEROLE`

  For descriptions and explanations of privileges Immuta needs to enforce policies and maintain state in Databricks Lakebase, see the [Databricks Lakebase connection reference guide](/SaaS/configuration/integrations/databricks/databricks-lakebase/reference-guides/databricks-lakebase-integration.md#required-databricks-lakebase-privileges).

## Register a Databricks Lakebase connection

1. In Immuta, click <i class="fa-database">:database:</i> **Data** and select **Connections** in the navigation menu.
2. Click the **+ Add Connection** button.
3. Select the **Databricks Lakebase** tile.
4. Enter the host connection information:
   1. **Display Name:** This is the name of your new connection. This name will be used in the API (`connectionKey`), in data source names from the host, and on the connections page. Avoid the use of periods (`.`) or [restricted words](#user-content-fn-1)[^1] in your connection name.
   2. **Hostname**: The host can be found by clicking **Connect** in your Databricks Lakebase console. See the [Databricks Lakebase docs](https://docs.databricks.com/aws/en/oltp/projects/connection-strings#connection-string-format) for additional details.
   3. **Port**: The default PostgreSQL port used for Databricks Lakebase is `5432`.
   4. **Database**: The database can be found by clicking **Connect** in your Databricks Lakebase console. The default is `databricks_postgres`.
5. Enter privileged credentials to register the connection using OAuth M2M:
   1. Follow Databricks documentation to create an OAuth token for machine-to-machine authentication for the Immuta service principal and assign this service principal the [privileges listed above](#permissions) for the Databricks Lakebase database.
   2. Fill out the **Workspace URL** (e.g., `https://<your workspace name>.cloud.databricks.com`).
   3. Fill out the **Client ID**. This is a combination of letters, numbers, or symbols, used as a public identifier and is the [client ID displayed in Databricks when creating the client secret for the service principal](https://docs.databricks.com/en/dev-tools/auth/oauth-m2m.html#step-3-create-an-oauth-secret-for-a-service-principal).
   4. Enter the **Client Secret** you created above. Immuta uses this secret to authenticate with the authorization server when it requests a token.
6. Click **Save Connection**.

## Map users

**Requirement**: `USER_ADMIN` Immuta permission

Map PostgreSQL usernames to each Immuta user account to ensure Immuta properly enforces policies when the user queries the Databricks Lakebase objects in PostgreSQL.

The instructions below illustrate how to do this for individual users, but you can also configure user mapping in your [IAM connection on the app settings page](/SaaS/configuration/people/users-index/how-to-guides/external-user-mapping.md#configure-external-user-id-mapping-on-app-settings-page).

1. Click **People** and select **Users** in the navigation menu.
2. Click the user's **name** to navigate to their page and scroll to the **External User Mapping** section.
3. Click **Edit** in the **PostgreSQL** row.
4. Select one of the following options from the dropdown:
   1. Select **PostgreSQL Username** to map the PostgreSQL username to the Immuta user and enter the PostgreSQL username in the field. Username mapping is case insensitive.
   2. Select **Unset (fallback to Immuta username)** to use the Immuta username as the assumed PostgreSQL username. Use this option if the user's PostgreSQL username exactly matches the user's Immuta username. Username mapping is case insensitive.
   3. Select **None (user does not exist in PostgreSQL)** if this is an Immuta-only user. This option will improve performance for Immuta users who do not have a mapping to PostgreSQL users and will be automatically selected by Immuta if an Immuta user is not found in PostgreSQL. To ensure your PostgreSQL users have policies correctly applied, manually map their usernames using the first option above.
5. Click **Save.**

[^1]: Your display name cannot be any of the following words: `data`, `connection`, `object`, `crawl`, `search`, `settings`, `metadata`, `permission`, `sync`, `bulk`, and `upgrade`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.immuta.com/SaaS/configuration/integrations/databricks/databricks-lakebase/register-a-databricks-lakebase-connection.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.