> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/2025.1/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/2025.1/configuration/integrations/registering-metadata/connections/how-to-guides/use-the-connection-upgrade-manager.md). # Use the Connection Upgrade Manager {% hint style="info" %} This feature is available to all 2025.1+ tenants. Contact your Immuta representative to enable this feature. {% endhint %} ### Supported technologies * Databricks Unity Catalog * Snowflake ### 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 **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 Databricks Unity Catalog or Snowflake. 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.](#user-content-fn-1)[^1] * [`SELECT` on all tables and views registered in Immuta](#user-content-fn-2)[^2]. 2. [Grant the new Snowflake role](https://docs.snowflake.com/en/sql-reference/sql/grant-role) to the [Immuta system user](#user-content-fn-3)[^3] 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 %} {% endtabs %} 5. Click **Next**. 6. Click **Upgrade Connection**. 7. Click the [link to the docs](/2025.1/configuration/integrations/registering-metadata/connections/reference-guides/upgrading-to-connections/before-you-begin.md) 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](/2025.1/configuration/integrations/registering-metadata/connections/how-to-guides/use-the-connection-upgrade-manager/troubleshooting.md) 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](/2025.1/configuration/integrations/registering-metadata/connections/reference-guides/connections-reference-guide.md#object-sync) is not on. To allow Immuta to discover new objects and created data sources for them, finalize your upgrade. 1. Select **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]: You must specify the Snowflake object type when granting `REFERENCES` on the table or view. For example, running `GRANT REFERENCES ON ALL TABLES` will grant this privilege to the standard table object type, but not to Iceberg tables or external tables. Instead, you would also have to run `GRANT REFERENCES ON ALL ICEBERG TABLES` and `GRANT REFERENCES ON ALL EXTERNAL TABLES`. [^2]: Only required when using [identification](/2025.1/configuration/manage-data-metadata/data-discovery/how-to-guides/enable-sdd.md) or specialized masking policies that require fingerprinting.\ \ You must specify the Snowflake object type when granting `SELECT` on the table or view. For example, running `GRANT SELECT ON ALL TABLES` will grant this privilege to the standard table object type, but not to Iceberg tables or external tables. Instead, you would also have to run `GRANT SELECT ON ALL ICEBERG TABLES` and `GRANT SELECT ON ALL EXTERNAL TABLES`. [^3]: The username of this system user can be found on the credentials tab of the upgrade UI. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.immuta.com/2025.1/configuration/integrations/registering-metadata/connections/how-to-guides/use-the-connection-upgrade-manager.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.