[Yandex Cloud documentation](../../index.md) > [Yandex Managed Service for Trino](../index.md) > [Step-by-step guides](index.md) > Object access rules > Assigning rules for schemas

# Assigning access rules for schemas in Managed Service for Trino

Schema access rules decide which users own which schemas in a Managed Service for Trino cluster.

{% note info %}

The schema owner can create, update, or delete the schema. To do this, the owner needs the `ALL` access level for the catalog that contains the schema.

{% endnote %}

For each user-schema pair, the rules apply as follows:
* Rules are checked in the order of their declaration. The first rule matching the user-schema pair applies.
* If none of the rules match the user-schema pair, the user is not the schema owner.
* If no schema access rules are set, each user owns all schemas in all catalogs.

## Setting rules when creating a cluster {#set-at-create}

You can set schema access rules when creating a Managed Service for Trino cluster.

{% note warning %}
  
Schema names specified in the rules are not validated. If a schema name contains an error, the rule will not apply correctly.
  
{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder where you want to create a Managed Service for Trino cluster.
  1. Navigate to **Managed Service for Trino**.
  1. Click **Create cluster** and set the cluster parameters.
  1. Under **Access settings**, click ![image](../../_assets/console-icons/chevron-down.svg).
  1. In the **Schemas** field, click **Add rule**.
  1. In the window that opens, set up the rule:

     1. Optionally, provide a rule description in the **Comment** field.

     1. Optionally, in the **Users** field, select the users the rule applies to:
        1. Click **Add**.
        1. Select the users from the list that opens. Use the search bar above the list to find particular users.
        1. To deselect a user selected by mistake, click that user again in the list.
        
        If no user is selected, the rule applies to all users.

     1. Optionally, in the **Groups** field, select the user groups the rule applies to:
        1. Click **Add**.
        1. From the list that opens, select the groups. Use the search bar above the list to find particular groups.
        1. To delete a group selected by mistake, click it again in the list.
        
        If you select no groups, the rule applies to all user groups.

     1. In the **Schema owner** field, select whether or not the user owns the schema:
        * `YES`: The user owns the schema.
        * `NO`: The user does not own the schema.

     1. Optionally, specify full names of the schemas the rule will apply to, formatted as `<catalog_name>.<schema_name>`. Use a separate field for each part of the name.

        1. Select format for the catalogs:
           * **Name**: Select catalog names. You can only select catalogs added in **Catalogs**.
           * **Name (regular expression)**: Enter a regular expression for catalog names.
           * **Not specified**: The `<catalog_name>` field may contain any value.

        1. Select format for the schemas:
           * **Name**: Select schema names.
           * **Name (regular expression)**: Enter a regular expression for schema names.
           * **Not specified**: The `<schema_name>` field may contain any value.

  1. Add other rules in the same way as needed.
  1. To delete a rule added by mistake, click ![trash-bin](../../_assets/console-icons/trash-bin.svg) in the line with this rule.
  1. Click **Create**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To set schema access rules:

  1. Create a file named `access_control.yaml` and paste the following code into it:

     ```yaml
     schemas:
       # Rule 1
       - owner: <whether_or_not_user_owns_schema>
         catalog:
           name_regexp: <regular_expression>
         schema:
           names:
             any: [<list_of_schema_names>]
           name_regexp: <regular_expression>
         groups: [<list_of_group_IDs>]
         users: [<list_of_user_IDs>]
         description: <rule_description>
       # Rule 2
       - <Rule_2_parameters>
       ...
       # Rule N
       - <Rule_N_parameters>
     ```

     Where:

     * `schemas`: List of schema rules. Each rule contains the required `owner` parameter, as well as the optional `catalog`, `schema`, `groups`, `users`, and `description` parameters.

     * `owner`: Whether or not the user owns the schema:
       * `YES`: The user owns the schema.
       * `NO`: The user does not own the schema.

     * Combined, `catalog` and `schema` define the schemas the rule will apply to. Each of them is optional.

       * `catalog`: Catalogs set using the `name_regexp` parameter (regular expression for catalog names).

         Omitting the `catalog` section is equivalent to using the `.*` regular expression.

       * `schema`: Schemas specified by one of the following:
         * `names`: List of schema names.
         * `name_regexp`: Regular expression for schema names.

         Omitting the `schema` section is equivalent to using the `.*` regular expression.

       {% note info %}

       In Managed Service for Trino, full schema name follows this template: `<catalog_name>.<schema_name>`. The rule applies to a schema only if its full name is consistent with all the specified parameters.

       {% endnote %}

     * The `users` and `groups` parameters define users the rule applies to.
     
       * `users`: List of user IDs. The rule will only apply to the specified users.
     
       * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
     
       You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
     
     * `description`: Rule description.

  1. View the description of the CLI command for creating a cluster:

     ```bash
     yc managed-trino cluster create --help
     ```

  1. Run this command:

     ```bash
     yc managed-trino cluster create \
       ...
       --access-control-from-file access_control.yaml
     ```

     For available cluster parameters and their descriptions, see [this guide](cluster-create.md#create-cluster).

- Terraform {#tf}

  1. Create a Terraform configuration file describing your [infrastructure](cluster-create.md).
  
  1. Add the `yandex_trino_access_control` resource with the `schemas` rule list to the configuration file.
 
     ```hcl
     resource "yandex_trino_cluster" "<cluster_name>" {
       ...
     }

     resource "yandex_trino_catalog" "<catalog_1_name>" {
       ...
     }

     resource "yandex_trino_catalog" "<catalog_2_name>" {
       ...
     }

     ...

     resource "yandex_trino_catalog" "<catalog_N_name>" {
       ...
     }

     resource "yandex_trino_access_control" "trino_access_control" {
       ...
       cluster_id  = yandex_trino_cluster.<cluster_name>.id
       schemas = [
         # Rule 1
         {
           owner         = "<whether_or_not_user_owns_schema>"
           catalog       = {
             ids         = [
               yandex_trino_catalog.<catalog_1_name>.id,
               yandex_trino_catalog.<catalog_2_name>.id,
               ... 
               yandex_trino_catalog.<catalog_N_name>.id
             ]
             name_regexp = "<regular_expression>"
           }
           schema        = {
             names       = ["<list_of_schema_names>"]
             name_regexp = "<regular_expression>"
           }
           users         = ["<list_of_user_IDs>"]
           groups        = ["<list_of_group_IDs>"]
           description   = "<rule_description>"
         },
         # Rule 2
         {
           ... 
         },
         ...
         # Rule N
         {
           ... 
         }
       ]
       ...
     }
     ```

     Where:

     * `schemas`: List of schema rule sections. Each rule contains the required `owner` parameter, as well as the optional `catalog`, `schema`, `groups`, `users`, and `description` parameters.

     * `owner`: Whether or not the user owns the schema:
       * `YES`: The user owns the schema.
       * `NO`: The user does not own the schema.

     * Combined, `catalog` and `schema` define the schemas the rule will apply to. Each of them is optional.

       * `catalog`: Catalogs specified by one of the following:
         * `ids`: List of catalog IDs. These catalogs must be created in the same manifest.
         * `name_regexp`: Regular expression for catalog names.

         Omitting the `catalog` section is equivalent to using the `.*` regular expression.

       * `schema`: Schemas specified by one of the following:
         * `names`: List of schema names.
         * `name_regexp`: Regular expression for schema names.

         Omitting the `schema` section is equivalent to using the `.*` regular expression.

       {% note info %}

       In Managed Service for Trino, full schema name follows this template: `<catalog_name>.<schema_name>`. The rule applies to a schema only if its full name is consistent with all the specified parameters.

       {% endnote %}

     * The `users` and `groups` parameters define users the rule applies to.
     
       * `users`: List of user IDs. The rule will only apply to the specified users.
     
       * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
     
       You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
     
     * `description`: Rule description.

  1. Make sure the settings are correct.
  
      1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
      1. Run this command:
      
         ```bash
         terraform validate
         ```
      
         Terraform will show any errors found in your configuration files.
  
  1. Confirm resource changes.
  
      1. Run this command to view the planned changes:
      
         ```bash
         terraform plan
         ```
      
         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
      
      1. If everything looks correct, apply the changes:
         1. Run this command:
      
            ```bash
            terraform apply
            ```
      
         1. Confirm updating the resources.
         1. Wait for the operation to complete.
 
  For more information, see [this Terraform provider guide](../../terraform/resources/trino_access_control.md).

- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

  1. Create a file named `body.json` and paste the following code into it:

      ```json
      {
        <cluster_parameters>
        ...
        "trino": {
          "catalogs": [
            {
              "name": "catalog_1_name",
              ...
            },
            {
              "name": "catalog_2_name",
              ...
            },
            ...
            {
              "name": "catalog_N_name",
              ...
            }
          ]
          ...
          "accessControl": {
            "schemas": [
              {
                "owner": "<whether_or_not_user_owns_schema>",
                "catalog": {
                  "names": {
                    "any": [
                      "<catalog_1_name>",
                      "<catalog_2_name>",
                      ...
                      "<catalog_N_name>"
                    ]
                  },
                  "nameRegexp": "<regular_expression>"
                },
                "schema": {
                  "names": {
                    "any": [
                      "<list_of_schema_names>"
                    ]
                  },
                  "nameRegexp": "<regular_expression>"
                },
                "users": [
                  "<list_of_user_IDs>"
                ],
                "groups": [
                  "<list_of_group_IDs>"
                ],
                "description": "<rule_description>"
              },
              {
                <Rule_2_section>
              },
              ...
              {
                <Rule_N_section>
              }
            ]
          }
        }
      }
      ```

      Where:

      * `accessControl`: Configuration of access permissions within the cluster.

      * `schemas`: List of schema rule sections. Each rule contains the required `owner` parameter, as well as the optional `catalog`, `schema`, `groups`, `users`, and `description` parameters.

      * `owner`: Whether or not the user owns the schema:
        * `YES`: The user owns the schema.
        * `NO`: The user does not own the schema.

      * Combined, `catalog` and `schema` define the schemas the rule will apply to. Each of them is optional.

        * `catalog`: Catalogs specified by one of the following:
          * `names`: List of catalog names. You must create catalogs within the same [Cluster.Create](../api-ref/Cluster/create.md) call.
          * `nameRegexp`: Regular expression for catalog names.

          Omitting the `catalog` section is equivalent to using the `.*` regular expression.

        * `schema`: Schemas specified by one of the following:
          * `names`: List of schema names.
          * `nameRegexp`: Regular expression for schema names.

          Omitting the `schema` section is equivalent to using the `.*` regular expression.

        {% note info %}

        In Managed Service for Trino, full schema name follows this template: `<catalog_name>.<schema_name>`. The rule applies to a schema only if its full name is consistent with all the specified parameters.

        {% endnote %}

      * The `users` and `groups` parameters define users the rule applies to.
      
        * `users`: List of user IDs. The rule will only apply to the specified users.
      
        * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
      
        You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
      
      * `description`: Rule description.

      For available cluster parameters and their descriptions, see [this guide](cluster-create.md#create-cluster).

  1. Call the [Cluster.Create](../api-ref/Cluster/create.md) method, e.g., via the following [cURL](https://curl.se/) request:

      ```bash
      curl \
          --request POST \
          --header "Authorization: Bearer $IAM_TOKEN" \
          --url 'https://trino.api.cloud.yandex.net/managed-trino/v1/clusters'
          --data '@body.json'
      ```

  1. View the [server response](../api-ref/Cluster/create.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and place it in an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

  1. Create a file named `body.json` and paste the following code into it:

      ```json
      {
        <cluster_parameters>
        ...
        "trino": {
          "catalogs": [
            {
              "name": "catalog_1_name",
              ...
            },
            {
              "name": "catalog_2_name",
              ...
            },
            ...
            {
              "name": "catalog_N_name",
              ...
            }
          ]
          ...
          "access_control": {
            "schemas": [
              {
                "owner": "<whether_or_not_user_owns_schema>",
                "catalog": {
                  "names": {
                    "any": [
                      "<catalog_1_name>",
                      "<catalog_2_name>",
                      ...
                      "<catalog_N_name>"
                    ]
                  },
                  "name_regexp": "<regular_expression>"
                },
                "schema": {
                  "names": {
                    "any": [
                      "<list_of_schema_names>"
                    ]
                  },
                  "name_regexp": "<regular_expression>"
                },
                "users": [
                  "<list_of_user_IDs>"
                ],
                "groups": [
                  "<list_of_group_IDs>"
                ],
                "description": "<rule_description>"
              },
              {
                <Rule_2_section>
              },
              ...
              {
                <Rule_N_section>
              }
            ]
          }
        }
      }
      ```

      Where:

      * `access_control`: Configuration of access permissions within the cluster.

      * `schemas`: List of schema rule sections. Each rule contains the required `owner` parameter, as well as the optional `catalog`, `schema`, `groups`, `users`, and `description` parameters.

      * `owner`: Whether or not the user owns the schema:
        * `YES`: The user owns the schema.
        * `NO`: The user does not own the schema.

      * Combined, `catalog` and `schema` define the schemas the rule will apply to. Each of them is optional.

        * `catalog`: Catalogs specified by one of the following:
          * `names`: List of catalog names. You must create catalogs within the same [ClusterService/Create](../api-ref/grpc/Cluster/create.md) call.
          * `name_regexp`: Regular expression for catalog names.

          Omitting the `catalog` section is equivalent to using the `.*` regular expression.

        * `schema`: Schemas specified by one of the following:
          * `names`: List of schema names.
          * `name_regexp`: Regular expression for schema names.

          Omitting the `schema` section is equivalent to using the `.*` regular expression.

        {% note info %}

        In Managed Service for Trino, full schema name follows this template: `<catalog_name>.<schema_name>`. The rule applies to a schema only if its full name is consistent with all the specified parameters.

        {% endnote %}

      * The `users` and `groups` parameters define users the rule applies to.
      
        * `users`: List of user IDs. The rule will only apply to the specified users.
      
        * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
      
        You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
      
      * `description`: Rule description.

      For available cluster parameters and their descriptions, see [this guide](cluster-create.md#create-cluster).

  1. Call the [ClusterService/Create](../api-ref/grpc/Cluster/create.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

      ```bash
      grpcurl \
          -format json \
          -import-path ~/cloudapi/ \
          -import-path ~/cloudapi/third_party/googleapis/ \
          -proto ~/cloudapi/yandex/cloud/trino/v1/cluster_service.proto \
          -rpc-header "Authorization: Bearer $IAM_TOKEN" \
          -d @ \
          trino.api.cloud.yandex.net:443 \
          yandex.cloud.trino.v1.ClusterService.Create \
          < body.json
      ```

  1. Check the [server response](../api-ref/grpc/Cluster/create.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Setting rules for an existing cluster {#set-at-update}

You can set or update schema access rules for an existing Managed Service for Trino cluster.

{% note warning %}
  
Schema names specified in the rules are not validated. If a schema name contains an error, the rule will not apply correctly.
  
{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), navigate to the relevant folder.
  1. Navigate to **Managed Service for&nbsp;Trino**.
  1. Click the cluster name.
  1. Go to **Access settings** → **Schemas**.
  1. To add a rule, click **Add rule**. In the window that opens, set up the rule:

     1. Optionally, provide a rule description in the **Comment** field.

     1. Optionally, in the **Users** field, select the users the rule applies to:
        1. Click **Add**.
        1. Select the users from the list that opens. Use the search bar above the list to find particular users.
        1. To deselect a user selected by mistake, click that user again in the list.
        
        If no user is selected, the rule applies to all users.

     1. Optionally, in the **Groups** field, select the user groups the rule applies to:
        1. Click **Add**.
        1. From the list that opens, select the groups. Use the search bar above the list to find particular groups.
        1. To delete a group selected by mistake, click it again in the list.
        
        If you select no groups, the rule applies to all user groups.

     1. In the **Schema owner** field, select whether or not the user owns the schema:
        * `YES`: The user owns the schema.
        * `NO`: The user does not own the schema.

     1. Optionally, specify full names of the schemas the rule will apply to, formatted as `<catalog_name>.<schema_name>`. Use a separate field for each part of the name.

        1. Select format for the catalogs:
           * **ID**: Select catalog IDs. You can only select catalogs from those present in the cluster.
           * **Name**: Select catalog names. You can only select catalogs existing in the cluster.
           * **Name (regular expression)**: Enter a regular expression for catalog names.
           * **Not specified**: The `<catalog>` field may contain any value.

        1. Select format for the schemas:
           * **Name**: Select schema names.
           * **Name (regular expression)**: Enter a regular expression for schema names.
           * **Not specified**: The `<schema_name>` field may contain any value.

  1. Add other rules in the same way as needed.
  1. To edit a rule:
     1. Click ![trash-bin](../../_assets/console-icons/pencil.svg) in the line with this rule.
     1. Update the rule settings and click **Update**.
  1. To delete a rule you no longer need, click ![trash-bin](../../_assets/console-icons/trash-bin.svg) in the line with this rule.
  1. Click **Save changes**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To set schema access rules:

  1. If you have not set any access rules yet, create a file named `access_control.yaml` and paste the following into it:

     ```yaml
     schemas:
       # Rule 1
       - owner: <whether_or_not_user_owns_schema>
         catalog:
           ids:
             any: [<list_of_catalog_IDs>]
           names:
             any: [<list_of_catalog_names>]
           name_regexp: <regular_expression>
         schema:
           names:
             any: [<list_of_schema_names>]
           name_regexp: <regular_expression>
         groups: [<list_of_group_IDs>]
         users: [<list_of_user_IDs>]
         description: <rule_description>
       # Rule 2
       - <Rule_2_parameters>
       ...
       # Rule N
       - <Rule_N_parameters>
     ```

     Where:

     * `schemas`: List of schema rules. Each rule contains the required `owner` parameter, as well as the optional `catalog`, `schema`, `groups`, `users`, and `description` parameters.

     * `owner`: Whether or not the user owns the schema:
       * `YES`: The user owns the schema.
       * `NO`: The user does not own the schema.

     * Combined, `catalog` and `schema` define the schemas the rule will apply to. Each of them is optional.

       * `catalog`: Catalogs specified by one of the following:
         * `ids`: List of catalog IDs. These must be the existing catalogs.
         * `names`: List of catalog names. These must be the existing catalogs.
         * `name_regexp`: Regular expression for catalog names.

         Omitting the `catalog` section is equivalent to using the `.*` regular expression.

       * `schema`: Schemas specified by one of the following:
         * `names`: List of schema names.
         * `name_regexp`: Regular expression for schema names.

         Omitting the `schema` section is equivalent to using the `.*` regular expression.

       {% note info %}

       In Managed Service for Trino, full schema name follows this template: `<catalog_name>.<schema_name>`. The rule applies to a schema only if its full name is consistent with all the specified parameters.

       {% endnote %}

     * The `users` and `groups` parameters define users the rule applies to.
     
       * `users`: List of user IDs. The rule will only apply to the specified users.
     
       * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
     
       You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
     
     * `description`: Rule description.

  1. If you have already set the access rules, open `access_control.yaml` and edit it as needed. You can:

     * Add new rules.
     * Update the existing ones.
     * Delete the rules you no longer need.

  1. Run this command:

     ```bash
     yc managed-trino cluster set-access-control <cluster_name_or_ID> \
       --from-file access_control.yaml
     ```

     You can get the cluster ID and name with the [list of clusters in the folder](cluster-list.md#list-clusters).

- Terraform {#tf}

  1. Open the current Terraform configuration file with the infrastructure plan.
  
      To learn how to create this file, refer to [Creating a cluster](cluster-create.md).
  
  1. If you have not set any access rules yet, add the `yandex_trino_access_control` resource containing the `schemas` rule list.
 
     ```hcl
     resource "yandex_trino_cluster" "<cluster_name>" {
       ...
     }

     resource "yandex_trino_catalog" "<catalog_1_name>" {
       ...
     }

     resource "yandex_trino_catalog" "<catalog_2_name>" {
       ...
     }

     ...

     resource "yandex_trino_catalog" "<catalog_N_name>" {
       ...
     }

     resource "yandex_trino_access_control" "trino_access_control" {
       ...
       cluster_id  = yandex_trino_cluster.<cluster_name>.id
       schemas = [
         # Rule 1
         {
           owner         = "<whether_or_not_user_owns_schema>"
           catalog       = {
             ids         = [
               yandex_trino_catalog.<catalog_1_name>.id,
               yandex_trino_catalog.<catalog_2_name>.id,
               ... 
               yandex_trino_catalog.<catalog_N_name>.id
             ]
             name_regexp = "<regular_expression>"
           }
           schema        = {
             names       = ["<list_of_schema_names>"]
             name_regexp = "<regular_expression>"
           }
           users         = ["<list_of_user_IDs>"]
           groups        = ["<list_of_group_IDs>"]
           description   = "<rule_description>"
         },
         # Rule 2
         {
           ... 
         },
         ...
         # Rule N
         {
           ... 
         }
       ]
       ...
     }
     ```

     Where:

     * `schemas`: List of schema rule sections. Each rule contains the required `owner` parameter, as well as the optional `catalog`, `schema`, `groups`, `users`, and `description` parameters.

     * `owner`: Whether or not the user owns the schema:
       * `YES`: The user owns the schema.
       * `NO`: The user does not own the schema.

     * Combined, `catalog` and `schema` define the schemas the rule will apply to. Each of them is optional.

       * `catalog`: Catalogs specified by one of the following:
         * `ids`: List of catalog IDs. These catalogs must be created in the same manifest.
         * `name_regexp`: Regular expression for catalog names.

         Omitting the `catalog` section is equivalent to using the `.*` regular expression.

       * `schema`: Schemas specified by one of the following:
         * `names`: List of schema names.
         * `name_regexp`: Regular expression for schema names.

         Omitting the `schema` section is equivalent to using the `.*` regular expression.

       {% note info %}

       In Managed Service for Trino, full schema name follows this template: `<catalog_name>.<schema_name>`. The rule applies to a schema only if its full name is consistent with all the specified parameters.

       {% endnote %}

     * The `users` and `groups` parameters define users the rule applies to.
     
       * `users`: List of user IDs. The rule will only apply to the specified users.
     
       * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
     
       You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
     
     * `description`: Rule description.

  1. If you have already set the access rules, edit the `yandex_trino_access_control` resource description. You can:

     * Add new rules.
     * Update the existing ones.
     * Delete the rules you no longer need.

  1. Make sure the settings are correct.
  
      1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
      1. Run this command:
      
         ```bash
         terraform validate
         ```
      
         Terraform will show any errors found in your configuration files.
  
  1. Confirm resource changes.
  
      1. Run this command to view the planned changes:
      
         ```bash
         terraform plan
         ```
      
         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
      
      1. If everything looks correct, apply the changes:
         1. Run this command:
      
            ```bash
            terraform apply
            ```
      
         1. Confirm updating the resources.
         1. Wait for the operation to complete.
 
  For more information, see [this Terraform provider guide](../../terraform/resources/trino_access_control.md).

- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

  1. If you have not set any access rules yet, create a file named `body.json` and paste the following code into it:

      ```json
      {
        "updateMask": "trino.accessControl.schemas",
        "trino": {
          "accessControl": {
            "schemas": [
              {
                "owner": "<whether_or_not_user_owns_schema>",
                "catalog": {
                  "ids": {
                    "any": [
                      "<list_of_catalog_IDs>"
                    ]
                  },
                  "names": {
                    "any": [
                      "<list_of_catalog_names>"
                    ]
                  },
                  "nameRegexp": "<regular_expression>"
                },
                "schema": {
                  "names": {
                    "any": [
                      "<list_of_schema_names>"
                    ]
                  },
                  "nameRegexp": "<regular_expression>"
                },
                "users": [
                  "<list_of_user_IDs>"
                ],
                "groups": [
                  "<list_of_group_IDs>"
                ],
                "description": "<rule_description>"
              },
              {
                <Rule_2_section>
              },
              ...
              {
                <Rule_N_section>
              }
            ]
          }
        }
      }
      ```

      Where:

      * `updateMask`: Comma-separated list of parameters to update.

          {% note warning %}

          When you update a cluster, all parameters of the object you are modifying will be reset to their defaults unless explicitly provided in the request. To avoid this, list the settings you want to change in the `updateMask` parameter.

          {% endnote %}

      * `accessControl`: Access rule configuration in the cluster.

      * `schemas`: List of schema rule sections. Each rule contains the required `owner` parameter, as well as the optional `catalog`, `schema`, `groups`, `users`, and `description` parameters.

      * `owner`: Whether or not the user owns the schema:
        * `YES`: The user owns the schema.
        * `NO`: The user does not own the schema.

      * Combined, `catalog` and `schema` define the schemas the rule will apply to. Each of them is optional.

        * `catalog`: Catalogs specified by one of the following:
          * `ids`: List of catalog IDs. These must be the existing catalogs.
          * `names`: List of catalog names. These must be the existing catalogs.
          * `nameRegexp`: Regular expression for catalog names.

          Omitting the `catalog` section is equivalent to using the `.*` regular expression.

        * `schema`: Schemas specified by one of the following:
          * `names`: List of schema names.
          * `nameRegexp`: Regular expression for schema names.

          Omitting the `schema` section is equivalent to using the `.*` regular expression.

        {% note info %}

        In Managed Service for Trino, full schema name follows this template: `<catalog_name>.<schema_name>`. The rule applies to a schema only if its full name is consistent with all the specified parameters.

        {% endnote %}

      * The `users` and `groups` parameters define users the rule applies to.
      
        * `users`: List of user IDs. The rule will only apply to the specified users.
      
        * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
      
        You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
      
      * `description`: Rule description.

  1. If you have already set the access rules, open the existing `body.json` rules file and edit it as needed. You can:

     * Add new rules.
     * Update the existing ones.
     * Delete the rules you no longer need.

  1. Call the [Cluster.Update](../api-ref/Cluster/update.md) method, e.g., via the following [cURL](https://curl.se/) request:

      ```bash
      curl \
        --request PATCH \
        --header "Authorization: Bearer $IAM_TOKEN" \
        --url 'https://trino.api.cloud.yandex.net/managed-trino/v1/clusters/<cluster_ID>'
        --data '@body.json'
      ```

      You can get the cluster ID with the [list of clusters](cluster-list.md#list-clusters) in the folder.

  1. Check the [server response](../api-ref/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

  1. If you have not set any access rules yet, create a file named `body.json` and paste the following code into it:

      ```json
      {
        "cluster_id": "<cluster_ID>",
        "update_mask": {
          "paths": [
            "trino.access_control.schemas"
          ]
        },
        "trino": {
          "access_control": {
            "schemas": [
              {
                "owner": "<whether_or_not_user_owns_schema>",
                "catalog": {
                  "ids": {
                    "any": [
                      "<list_of_catalog_IDs>"
                    ]
                  },
                  "names": {
                    "any": [
                      "<list_of_catalog_names>"
                    ]
                  },
                  "name_regexp": "<regular_expression>"
                },
                "schema": {
                  "names": {
                    "any": [
                      "<list_of_schema_names>"
                    ]
                  },
                  "name_regexp": "<regular_expression>"
                },
                "users": [
                  "<list_of_user_IDs>"
                ],
                "groups": [
                  "<list_of_group_IDs>"
                ],
                "description": "<rule_description>"
              },
              {
                <Rule_2_section>
              },
              ...
              {
                <Rule_N_section>
              }
            ]
          }
        }
      }
      ```

      Where:

      * `cluster_id`: Cluster ID.
          
          You can get the cluster ID with the [list of clusters](cluster-list.md#list-clusters) in the folder.

      * `update_mask`: List of parameters to update as an array of strings (`paths[]`).

          {% cut "Format for listing settings" %}

          ```yaml
          "update_mask": {
            "paths": [
              "<setting_1>",
              "<setting_2>",
              ...
              "<setting_N>"
            ]
          }
          ```

          {% endcut %}

          {% note warning %}

          When you update a cluster, all parameters of the object you are modifying will be reset to their defaults unless explicitly provided in the request. To avoid this, list the settings you want to change in the `update_mask` parameter.

          {% endnote %}

      * `access_control`: Access rule configuration in the cluster.

      * `schemas`: List of schema rule sections. Each rule contains the required `owner` parameter, as well as the optional `catalog`, `schema`, `groups`, `users`, and `description` parameters.

      * `owner`: Whether or not the user owns the schema:
        * `YES`: The user owns the schema.
        * `NO`: The user does not own the schema.

      * Combined, `catalog` and `schema` define the schemas the rule will apply to. Each of them is optional.

        * `catalog`: Catalogs specified by one of the following:
          * `ids`: List of catalog IDs. These must be the existing catalogs.
          * `names`: List of catalog names. These must be the existing catalogs.
          * `name_regexp`: Regular expression for catalog names.

          Omitting the `catalog` section is equivalent to using the `.*` regular expression.

        * `schema`: Schemas specified by one of the following:
          * `names`: List of schema names.
          * `name_regexp`: Regular expression for schema names.

          Omitting the `schema` section is equivalent to using the `.*` regular expression.

        {% note info %}

        In Managed Service for Trino, full schema name follows this template: `<catalog_name>.<schema_name>`. The rule applies to a schema only if its full name is consistent with all the specified parameters.

        {% endnote %}

      * The `users` and `groups` parameters define users the rule applies to.
      
        * `users`: List of user IDs. The rule will only apply to the specified users.
      
        * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
      
        You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
      
      * `description`: Rule description.

  1. If you have already set the access rules, open the existing `body.json` rules file and edit it as needed. You can:

     * Add new rules.
     * Update the existing ones.
     * Delete the rules you no longer need.

  1. Call the [ClusterService.Update](../api-ref/grpc/Cluster/update.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

      ```bash
      grpcurl \
        -format json \
        -import-path ~/cloudapi/ \
        -import-path ~/cloudapi/third_party/googleapis/ \
        -proto ~/cloudapi/yandex/cloud/trino/v1/cluster_service.proto \
        -rpc-header "Authorization: Bearer $IAM_TOKEN" \
        -d @ \
        trino.api.cloud.yandex.net:443 \
        yandex.cloud.trino.v1.ClusterService.Update \
        < body.json
      ```

  1. Check the [server response](../api-ref/grpc/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Example of setting schema access rules {#example}

Let's assume you need to specify schema owners in a Trino cluster as shown below:
1. The user with the `banned_user_id` ID does not own any schemas.
1. Users belonging to the groups whose IDs are `data_engineering_group_id` or `admins_group_id` own the `b2b` and `b2c` schemas in catalogs with the naming pattern of `dwh_.*`.
1. All other users do not own any schemas.

{% list tabs group=instructions %}

- CLI {#cli}

  The `access_control.yaml` file for this rule set looks like this:

  ```yaml
  schemas:
    - users:
        - banned_user_id
      owner: NO

    - groups:
        - data_engineering_group_id
        - admins_group_id
      schema:
        names:
          any:
            - b2b
            - b2c
      catalog:
        name_regexp: "dwh_.*"
      owner: YES
  ```

- Terraform {#tf}

  The configuration file for this rule set is as follows:

  ```hcl
  resource "yandex_trino_access_control" "trino_access_control" {
    ...
    cluster_id  = <cluster_ID>
    schemas = [
      {
        users         = ["banned_user_id"]
        owner         = "NO"
      },
      {
        groups        = ["data_engineering_group_id", "admins_group_id"]
        schema        = {
          names       = ["b2b", "b2c"]
        }        
        catalog       = {
          name_regexp = "dwh_.*"
        }
        owner         = "YES"
      }
    ]
    ...
  }
  ```

- REST API {#api}

  The `body.json` file for this rule set is as follows:

  ```json
  {
    "updateMask": "trino.accessControl.schemas",
    "trino": {
      "accessControl": {
        "schemas": [
          {
            "users": [
              "banned_user_id"
            ],
            "owner": "NO"
          },
          {
            "groups": [
              "data_engineering_group_id",
              "admins_group_id"
            ],
            "schema": {
              "names": {
                "any": [
                  "b2b",
                  "b2c"
                ]
              }
            },
            "catalog": {
              "nameRegexp": "dwh_.*"
            },
            "owner": "YES"
          }
        ]
      }
    }
  }
  ```

- gRPC API {#grpc-api}

  The `body.json` file for this rule set is as follows:

  ```json
  {
    "cluster_id": "<cluster_ID>",
    "update_mask": {
      "paths": [
        "trino.access_control.schemas"
      ]
    },
    "trino": {
      "access_control": {
        "schemas": [
          {
            "users": [
              "banned_user_id"
            ],
            "owner": "NO"
          },
          {
            "groups": [
              "data_engineering_group_id",
              "admins_group_id"
            ],
            "schema": {
              "names": {
                "any": [
                  "b2b",
                  "b2c"
                ]
              }
            },
            "catalog": {
              "name_regexp": "dwh_.*"
            },
            "owner": "YES"
          }
        ]
      }
    }
  }
  ```

{% endlist %}