# Use the Connection Upgrade Manager

### Supported technologies

* Databricks Unity Catalog
* Snowflake
* Trino

### Requirements

* An integration enabled on the Immuta app settings page
* Data sources registered
* Immuta global `GOVERNANCE` and `APPLICATION_ADMIN` permissions

## Begin your upgrade

1. Select <i class="fa-database">:database:</i> **Data** and then **Upgrade Manager** in the navigation menu. This tab will only be available if you have integrations ready for upgrade.
2. Click **Start Upgrade**.
3. **Display Name**: The display name represents the unique name of your connection and will be used as prefix in the name for all data objects associated with this connection. It will also appear as the display name in the UI and will be used in all API calls made to update or delete the connection.
4. Click **Next**.
5. Ensure Immuta has the correct credentials to connect to the data platform. Select the tab below for more information:

{% tabs %}
{% tab title="Databricks Unity Catalog" %}
Click **Validate Credentials** to ensure the access token can connect Immuta and Databricks Unity Catalog.
{% endtab %}

{% tab title="Snowflake" %}

1. [Create a Snowflake role](https://docs.snowflake.com/en/sql-reference/sql/create-role) with a minimum of the following permissions:
   * `USAGE` on all databases and schemas with registered data sources.
   * `REFERENCES` on all tables and views registered in Immuta.
   * [`SELECT` on all tables and views registered in Immuta](#user-content-fn-1)[^1].
2. [Grant the new Snowflake role](https://docs.snowflake.com/en/sql-reference/sql/grant-role) to the [Immuta system user](#user-content-fn-2)[^2] in your Snowflake environment.
3. Enter the new Snowflake role in the textbox.
4. Click **Validate Credentials** to ensure the role has been granted to the right user.
   {% endtab %}

{% tab title="Trino" %}
When possible, Immuta will populate your credentials from your data source registration. If you used multiple credentials to register data sources you will need to enter a single set of credentials for your system account.

**If Immuta populates the credentials**:

* Click **Validate Connection** to ensure the Trino cluster is running, and Immuta can connect to it.

**If you need to enter credentials**:

1. Create or select a Trino user with a minimum of these permissions:
   * `SELECT` on all tables you want registered in Immuta

2. Use the dropdown to select your authentication method:
   1. **Username and Password**: Enter the username and password for the system account user.
   2. **OAuth 2.0 with Client Secret**:
      * Fill out the **Token Endpoint** with the full URL of the identity provider. This is where the generated token is sent.
      * Fill out the **Client ID**. This is a combination of letters, numbers, or symbols, used as a public identifier. This is the subject of the generated token.
      * Enter the **Scope** (string). The scope limits the operations allowed in Trino by the access token. See the [OAuth 2.0 documentation](https://oauth.net/2/scope/) for details about scopes.
      * Enter the **Client Secret**. Immuta uses this secret to authenticate with the authorization server when it requests a token.
   3. **OAuth 2.0 with Client Certificate**:
      1. Fill out the **Token Endpoint** with the full URL of the identity provider. This is where the generated token is sent.
      2. Fill out the **Client ID**. This is a combination of letters, numbers, or symbols, used as a public identifier. This is the subject of the generated token.
      3. Enter the **Scope** (string). The scope limits the operations allowed in Trino by the access token. See the [OAuth 2.0 documentation](https://oauth.net/2/scope/) for details about scopes.
      4. Opt to fill out the **Resource** field with a URI of the resource where the requested token will be used.
      5. Enter the **x509 Certificate Thumbprint**. This identifies the corresponding key to the token and is often abbreviated as `x5t` or is called `sub` (Subject).
      6. Upload the **Client Certificate**, which is used to sign the authorization request.

3. Update your `immuta-access-control.properties` file and enter the Trino username into the `immuta.user.admin` field.

4. Click **Validate Connection** to ensure the Trino cluster is running, and Immuta can connect to it.
   {% endtab %}
   {% endtabs %}

5. Click **Next**.

6. Click **Upgrade Connection**.

7. Click [the link to the docs](https://documentation.immuta.com/saas/configuration/integrations/data-and-integrations/registering-a-connection/reference-guides/upgrading-to-connections/before-you-begin) to understand the impacts of the upgrade.

8. Click the checkbox to confirm understanding of the upgrade effects, and click **Yes, Upgrade Connection**.

The upgrade manager will then begin connecting your data sources with the tables in the backing technology. This may take some time to complete.

## Resolve any issues

While most upgrades will complete without any additional intervention, it may be necessary to resolve data sources that are not easily matched to the backing tables. See the [Troubleshooting guide](https://documentation.immuta.com/saas/configuration/integrations/data-and-integrations/registering-a-connection/how-to-guides/use-the-connection-upgrade-manager/troubleshooting) if you are prompted to **Resolve** in the upgrade manager.

## Complete your upgrade

Your connection is in an upgrade state until you finalize. In the upgrade state, policy will still be applied to your data sources, but [object sync](https://documentation.immuta.com/saas/configuration/integrations/data-and-integrations/reference-guides/connections-overview#object-sync) is not on. To allow Immuta to discover new objects and created data sources for them, finalize your upgrade.

1. Select <i class="fa-database">:database:</i> **Data** and then **Upgrade Manager** in the navigation menu. This tab will only be available if you have integrations ready for upgrade.
2. Click **Finalize** for the finished connection.

[^1]: Only required when using [identification](https://documentation.immuta.com/saas/configuration/tags/data-discovery) or [specialized masking policies that require fingerprinting](https://documentation.immuta.com/saas/govern/secure-your-data/authoring-policies-in-secure/data-policies/reference-guides/masking-matrix-functions#types-limited-to-snowflake).

[^2]: The username of this system user can be found on the credentials tab of the upgrade UI.