improve trino docs

zeevmoney · zeevmoney · commit 0869bda180b2 · 2025-11-20T13:12:45.000+02:00
diff --git a/docs/integrations/database-access-control/trino-integration.mdx b/docs/integrations/database-access-control/trino-integration.mdx
@@ -25,39 +25,40 @@ or other applications.
 ## Quick Start
 
 1. **Prepare Permit**
-   - Create a new [Permit environment](/manage-your-account/projects-and-env#creating-a-new-environment) dedicated to the Trino cluster.
-   - Copy the PDP API key from the dashboard.
+  - Create a new [Permit environment](/manage-your-account/projects-and-env#creating-a-new-environment) dedicated to the Trino cluster.
+  - Copy the PDP API key from the dashboard.
 2. **Sync the schema**
-   - Install the latest [Permit CLI](/how-to/permit-cli).
-   - Run `permit env apply trino --url http://<trino-host>:8080 --user <trino-user>` and point it at a user that can read cluster metadata.
-   - The CLI introspects catalogs, schemas, tables, functions, and (optionally) columns, then creates matching resources and actions in Permit.
+  - Install the latest [Permit CLI](/how-to/permit-cli).
+  - Run `permit env apply trino --url http://<trino-host>:8080 --user <trino-user>` and point it at a user that can read cluster metadata.
+  - The CLI introspects catalogs, schemas, tables, functions, and (optionally) columns, then creates matching resources and actions in Permit.
 3. **Deploy the PDP**
-   - Run a Permit PDP that targets the same environment. Ensure Trino can reach it (default port `7766`).
-   - Enable `PDP_ALLOW_UNAUTHENTICATED_TRINO=True` to allow unauthenticated Trino queries to be checked by the PDP.
+  - Run a Permit PDP that targets the same environment. Ensure Trino can reach it (default port `7766`).
+  - Enable `PDP_ALLOW_UNAUTHENTICATED_TRINO=True` to allow unauthenticated Trino queries to be checked by the PDP.
+  - Optionally, [mount a Trino authz config file](/concepts/pdp/configuration#pdp_trino_authz_config_path) at to define filtering rules.
 4. **Configure Trino to use the PDP for access control**
-   - Configure the Trino's `/etc/trino/access-control.properties` to call the PDP:
-   ```yaml
-   access-control.name=opa
-   opa.policy.uri=http://<pdp-host>:7766/trino/allowed
-   opa.policy.row-filters-uri=http://<pdp-host>:7766/trino/row-filter
-   opa.policy.batch-column-masking-uri=http://<pdp-host>:7766/trino/batch-column-masking
-   opa.log-requests=true
-   opa.log-responses=true
-   ```
-   - Restart the Trino coordinator.
+  - Configure the Trino's `/etc/trino/access-control.properties` to call the PDP:
+  ```yaml
+  access-control.name=opa
+  opa.policy.uri=http://<pdp-host>:7766/trino/allowed
+  opa.policy.row-filters-uri=http://<pdp-host>:7766/trino/row-filter
+  opa.policy.batch-column-masking-uri=http://<pdp-host>:7766/trino/batch-column-masking
+  opa.log-requests=true
+  opa.log-responses=true
+  ```
+- Restart the Trino coordinator.
 5. **Assign policies**
-   - Use the [Permit Policy Editor](https://app.permit.io/policy-editor) (or via API, SDK,  etc.) to grant roles actions such as `trino_sys#ExecuteQuery` and table-level `SelectFromColumns`.
-   - Test queries as different users and confirm audit entries appear both in Permit and Trino.
-   - Use the [Permit Audit Logs](https://app.permit.io/audit-log) to review the access control decisions.
+  - Use the [Permit Policy Editor](https://app.permit.io/policy-editor) (or via API, SDK, etc.) to grant roles actions such as `trino_sys#ExecuteQuery` and table-level `SelectFromColumns`.
+  - Test queries as different users and confirm audit entries appear both in Permit and Trino.
+  - Use the [Permit Audit Logs](https://app.permit.io/audit-log) to review the access control decisions.
 
 Want a sandbox that shows the full stack running? Try the public demo: https://github.com/permitio/trino-authz-example
 
 :::warning Warning:
-Trino does not currently support passing an API key or credentials when calling external authorization endpoints. 
+Trino does not currently support passing an API key or credentials when calling external authorization endpoints.
 As a result, you must expose the PDP's Trino authorization routes (such as `/trino/allowed`, `/trino/row-filter`, `/trino/batch-column-masking`) without authentication, by setting `PDP_ALLOW_UNAUTHENTICATED_TRINO=True`.
 
-Because these endpoints are unauthenticated, **do not expose your PDP** to the public internet or any untrusted networks. 
-Always deploy the PDP behind a firewall or within a secure, trusted network accessible only by the Trino cluster. 
+Because these endpoints are unauthenticated, **do not expose your PDP** to the public internet or any untrusted networks.
+Always deploy the PDP behind a firewall or within a secure, trusted network accessible only by the Trino cluster.
 
 For more information, follow the [Trino issue](https://github.com/trinodb/trino/issues/27022) on this topic.
 :::
@@ -74,14 +75,14 @@ Access is granted only when the user is permitted for **all** required columns.
 This allows scenarios where a user lacks table-level permissions but can still read a safe subset of columns.
 
 ```mermaid
-%%{ 
+%%{
   init: {
     "theme": "base",
     "themeVariables": { "wrap": "false" },
-    "flowchart": { 
+    "flowchart": {
       "curve": "linear",
       "markdownAutoWrap":"false",
-      "wrappingWidth": "600" 
+      "wrappingWidth": "600"
     }
   }
 }%%
@@ -106,7 +107,8 @@ You can generate Permit column resources automatically with the CLI flag `--crea
 
 ### Column-masking
 
-Permit can instruct Trino to mask sensitive column values instead of blocking the query outright. Masks are defined in a YAML file that the PDP reads on startup:
+Permit can instruct Trino to mask sensitive column values instead of blocking the query outright.
+Masks are defined in a YAML file that the PDP reads on startup:
 
 ```24:38:trino-authz-example/trino-authz.yaml
 columnMasking:
@@ -125,7 +127,7 @@ columnMasking:
         view_expression: "CONCAT(SUBSTRING(description, 1, 10), '...')"
 ```
 
-Masks return only when the user (or role) has the corresponding Permit action. 
+Masks return only when the user (or role) has the corresponding Permit action.
 You can review the [Audit Logs](https://app.permit.io/audit-log) to see the Permit action checked on the table resource, causing the mask to be applied.
 
 For more information, see the [Trino documentation](https://trino.io/docs/current/security/opa-access-control.html#column-masking).
@@ -186,61 +188,61 @@ Every query to Trino triggers a call to the PDP. Permit returns `allow` or `deny
 
 ### Permit / Trino Resource Mapping
 
-When the Permit PDP receives an authorization request from Trino, it maps the request into a `permit.check()` call. 
+When the Permit PDP receives an authorization request from Trino, it maps the request into a `permit.check()` call.
 The resource name and actions are converted to the corresponding Trino resource and action the user is trying to perform.
 
-All queries are checked with the current Trino user's identity, with permissions on the "default" tenant. 
+All queries are checked with the current Trino user's identity, with permissions on the "default" tenant.
 You can use Trino's several Authentication mechanisms to identify the user, like [JWT](https://trino.io/docs/current/security/jwt.html) or [OAuth2](https://trino.io/docs/current/security/oauth2.html).
 
 By default, if the query does not match any resource or action in Permit, the request is denied. You are not required to create a resource for every table in your database.
 
 #### System Scope
 
-**Resource Name:** `trino_sys`  
-**Actions:** `ExecuteQuery`, `ImpersonateUser`, `SetSystemSessionProperty`  
+**Resource Name:** `trino_sys`
+**Actions:** `ExecuteQuery`, `ImpersonateUser`, `SetSystemSessionProperty`
 
 This resource represents the entire Trino system. Actions here apply at the highest level, governing general permissions such as running queries or impersonating users across the cluster.
 
 #### Catalog
 
-**Resource Name:** `trino_catalog_<catalog>`  
-**Actions:** `AccessCatalog`, `FilterCatalogs`, `DropCatalog`  
+**Resource Name:** `trino_catalog_<catalog>`
+**Actions:** `AccessCatalog`, `FilterCatalogs`, `DropCatalog`
 
 A catalog in Trino represents a data source connection—such as a database or data warehouse. This resource governs access and management permissions for that catalog.
 
 #### Schema
 
-**Resource Name:** `trino_schema_<catalog>_<schema>`  
-**Actions:** `ShowSchemas`, `CreateSchema`, `SetSchemaAuthorization`  
+**Resource Name:** `trino_schema_<catalog>_<schema>`
+**Actions:** `ShowSchemas`, `CreateSchema`, `SetSchemaAuthorization`
 
 A schema organizes database objects within a catalog, grouping related tables. This resource allows control over schema-level actions like listing, creating, or administering schemas.
 
 #### Table / View / Materialized View
 
-**Resource Name:** `trino_table_<catalog>_<schema>_<name>`  
-**Actions:** `SelectFromColumns`, `InsertIntoTable`, `FilterColumns`, `SetTableProperties`, custom row-filter and column-mask actions 
+**Resource Name:** `trino_table_<catalog>_<schema>_<name>`
+**Actions:** `SelectFromColumns`, `InsertIntoTable`, `FilterColumns`, `SetTableProperties`, custom row-filter and column-mask actions
 
-This resource covers tables, views, and materialized views within a schema, representing structured sets of data. 
+This resource covers tables, views, and materialized views within a schema, representing structured sets of data.
 Actions here usually correspond to reading, writing, filtering, or updating attributes of each table-like object.
 
 #### Column (optional)
 
-**Resource Name:** `trino_column_<catalog>_<schema>_<table>_<column>`  
-**Actions:** `SelectFromColumns`, custom column-mask actions  
+**Resource Name:** `trino_column_<catalog>_<schema>_<table>_<column>`
+**Actions:** `SelectFromColumns`, custom column-mask actions
 
 This resource represents a specific column within a table or view, and enables fine-grained access or masking rules at the column level.
 
 #### Function
 
-**Resource Name:** `trino_function_<catalog>_<schema>_<function>`  
-**Actions:** `ExecuteFunction`, `CreateFunction`  
+**Resource Name:** `trino_function_<catalog>_<schema>_<function>`
+**Actions:** `ExecuteFunction`, `CreateFunction`
 
 A function in Trino is a reusable computation or operation available within a schema. This resource is used to control who can execute or create that function.
 
 #### Procedure
 
-**Resource Name:** `trino_procedure_<catalog>_<schema>_<procedure>`  
-**Actions:** `ExecuteProcedure`  
+**Resource Name:** `trino_procedure_<catalog>_<schema>_<procedure>`
+**Actions:** `ExecuteProcedure`
 
 Procedures are database routines in Trino that perform complex operations. This resource represents permission to execute those procedures.
 
@@ -256,9 +258,9 @@ The Permit CLI can generate the Permit resources for your Trino schema automatic
 permit env apply trino --url http://<trino-host>:8080 --user <trino-user>
 
 # Usage: permit env apply trino [options]
-# 
+#
 # Apply permissions policy from a Trino schema, creating resources from catalogs, schemas, tables, columns.
-# 
+#
 # Options:
 #   --api-key [api-key]        API key for Permit authentication
 #   -u, --url <url>            Trino cluster URL (e.g., http://localhost:8080)
@@ -272,9 +274,9 @@ permit env apply trino --url http://<trino-host>:8080 --user <trino-user>
 
 The command will need permissions to read the Trino schema. You can use the `--user` flag to specify a user that has the necessary permissions.
 
-The command only adds resources. Removing a table or column in Trino does not delete the Permit resource automatically; you can remove the resource manually in the Permit UI. 
+The command only adds resources. Removing a table or column in Trino does not delete the Permit resource automatically; you can remove the resource manually in the Permit UI.
 
-Modifying the Trino schema, like adding a new table or column, will not automatically update the Permit resources. 
+Modifying the Trino schema, like adding a new table or column, will not automatically update the Permit resources.
 You will need to run the command again to add the new resources. Trino resources that are not mapped to Permit resources will be denied.
 
 ### PDP Trino config file
@@ -311,7 +313,7 @@ rowFilters:
     - action: filter_out_todo
 ```
 
-After updating the file, restart the PDP so the changes take effect.
+After updating the file, restart the PDP, so the changes take effect.
 
 ### Trino coordinator configuration
 
@@ -326,13 +328,13 @@ opa.log-requests=true
 opa.log-responses=true
 ```
 
-After updating the file, restart the coordinator so the plugin reloads its configuration.
+After updating the file, restart the coordinator, so the plugin reloads its configuration.
 
 ## Operational considerations
 
 ### Multiple access control systems
 
-Trino supports [multiple access control systems](https://trino.io/docs/current/security/built-in-system-access-control.html#multiple-access-control-systems). 
+Trino supports [multiple access control systems](https://trino.io/docs/current/security/built-in-system-access-control.html#multiple-access-control-systems).
 Using that, you can combine Permit authorization for application users, and Trino's built-in file-based access control for administrative users.
 
 ### Trino authentication
@@ -345,10 +347,10 @@ For more information, see the [Trino authentication documentation](https://trino
 
 ### Policy isolation
 
-We recommend using a dedicated Permit project and environments for the Trino cluster authorization. 
+We recommend using a dedicated Permit project and environments for the Trino cluster authorization.
 This will help you isolate the authorization decisions from the rest of your data.
 
-Your database schema can include many resources and actions. 
+Your database schema can include many resources and actions.
 Using a dedicated Permit project and environments will help you manage the complexity, follow audit trails, and isolate the authorization decisions from the rest of your data.
 
 Read more about [Permit projects and environments](/manage-your-account/projects-and-env).
