# Trino Connection Reference Guide

Using the Trino connection, you can register a Trino integration for your open-source Trino or Starburst Enterprise cluster. See the [Starburst (Trino) integration reference guide](/latest/configuration/integrations/starburst-trino/reference-guides/trino-overview.md) for additional details about the Trino integration.

## What does Immuta do in my Trino cluster?

### Registering a connection <a href="#registering-a-connection" id="registering-a-connection"></a>

Immuta utilizes [connections](/latest/configuration/integrations/registering-metadata/connections/reference-guides/connections-reference-guide.md) to register and manage data from your Trino cluster. Instead of registering individual catalogs, connections enable you to register an entire data platform at once. This approach simplifies data registration and allows Immuta to automatically monitor your Trino platform for changes. Data sources are then added or removed to reflect the current state of your data platform.

When the [connection is registered](/latest/configuration/integrations/starburst-trino/how-to-guides/register-a-trino-connection.md), Immuta ingests and stores connection metadata in the Immuta metadata database.

Immuta presents a hierarchical view of your data that reflects the hierarchy of objects in Trino after registration is complete:

* Cluster
* Catalog
* Schema
* Tables

Beyond making the registration of your data more intuitive, connections provide more control. Instead of performing operations on individual schemas or tables, you can perform operations (such as object sync) at the connection level.

See the [Connections reference guide](/latest/configuration/integrations/registering-metadata/connections/reference-guides/connections-reference-guide.md) for details about connections and how to manage them. To configure your Trino connection, see the [Register a Trino connection guide](/latest/configuration/integrations/starburst-trino/how-to-guides/register-a-trino-connection.md).

### Required Trino privileges

The privileges that the Trino connection requires align to the least privilege security principle. The table below describes the privilege required by the [`IMMUTA_SYSTEM_ACCOUNT`](#user-content-fn-1)[^1] user.

| Trino privilege        | User requiring the privilege | Explanation                                                                                |
| ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------ |
| `SELECT` on all tables | Immuta system account        | This privilege provides access to all the Trino tables that you want registered in Immuta. |

### Maintaining state with Trino

The following user actions spur various processes in the Trino connection so that Immuta data remains synchronous with data in Trino. The list below provides an overview of each process:

* **Data source created or updated**: Immuta registers data source metadata and stores that metadata in the Immuta metadata database.
* **Data source deleted**: Immuta deletes the data source metadata from the metadata database.
* [**User account is mapped to Immuta**](#user-registration-and-id-mapping): When a user account is mapped to Immuta, their metadata is stored in the metadata database.

## Supported object types <a href="#supported-object-types" id="supported-object-types"></a>

| Object type       | Subscription policy support | Data policy support  |
| ----------------- | --------------------------- | -------------------- |
| Table             | :white\_check\_mark:        | :white\_check\_mark: |
| View              | :white\_check\_mark:        | :white\_check\_mark: |
| Materialized view | :white\_check\_mark:        | :white\_check\_mark: |

## Security and compliance <a href="#security-and-compliance" id="security-and-compliance"></a>

### Authentication methods <a href="#authentication-methods" id="authentication-methods"></a>

The Trino integration supports the following authentication methods to register a connection. The credentials provided must be for an account with the permissions listed in the [Register a Trino connection page](/latest/configuration/integrations/starburst-trino/how-to-guides/register-a-trino-connection.md).

* **Username and password**: You can authenticate with your Starburst (Trino) username and password.
* **OAuth 2.0**: You can authenticate with OAuth 2.0. Immuta's OAuth authentication method uses the [Client Credentials Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow); when you register a data source, Immuta reaches out to your OAuth server to generate a JSON web token (JWT) and then passes that token to the Starburst (Trino) cluster. Therefore, when using OAuth authentication to create data sources in Immuta, configure your Starburst (Trino) cluster to use JWT authentication, not OpenID Connect or OAuth.

{% hint style="info" %}
**Data owner fallback**

When users query a Starburst (Trino) data source, Immuta sends the data owner username with the view SQL so that policies apply in the right context. However, there are two scenarios in which Immuta cannot retrieve and send the data owner username:

* The Starburst (Trino) cluster has an error when Immuta queries for the owner
* The data source has already been registered without an owner

If either of these scenarios occur, queries will fail. To avoid this error, you must set a global admin username. Contact your Immuta representative to configure the `globalAdminUsername` property.
{% endhint %}

### User registration and ID mapping <a href="#user-registration-and-id-mapping" id="user-registration-and-id-mapping"></a>

The built-in Immuta IAM can be used as a complete solution for authentication and user entitlement. However, you can connect your existing identity management provider to Immuta to use that system for authentication and user entitlement instead. Each of the [supported IAM protocols](/latest/releases/support-matrix.md#external-iams) includes a set of configuration options that enable Immuta to communicate with the IAM system and map the users, permissions, groups, and attributes into Immuta.

For policies to impact the right users, the user account in Immuta must be mapped to the user account in Trino. You can ensure these accounts are mapped correctly in the following ways:

* [Automatically](/latest/configuration/people/immuta-users/how-to-guides/external-user-mapping.md#configure-external-user-id-mapping-on-app-settings-page): If usernames in Trino align with usernames in the external IAM and those accounts align with an IAM attribute, you can enter that IAM attribute on the app settings page to automatically map user IDs in Immuta to Trino.
* [Manually](/latest/configuration/people/immuta-users/how-to-guides/external-user-mapping.md#manually-configure-external-user-id-mapping-on-a-users-page): You can manually map user IDs for individual users.

For guidance on connecting your IAM to Immuta, see the [how-to guide for your protocol](/latest/configuration/people/section-contents.md#how-to-guides).

[^1]: This user account is used by Immuta to manage the connection once it has been set up.


---

# Agent Instructions: 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:

```
GET https://documentation.immuta.com/latest/configuration/integrations/starburst-trino/reference-guides/trino-connection-reference-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.