> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/build/productize/connect-engine/trino/dedicated-trino.md).

# Dedicated Trino

Ship a Trino cluster as part of the Data Product. Vulcan provisions and owns one cluster per product.

Use this path when the Trino cluster should be part of the data product deployment itself. You don't manage the cluster separately from the product: a single vulcan trino resource provisions the coordinator and workers, generates catalogs from your depots or DataOS-provisioned secret catalogs, and runs the plan and run workflows.

This page covers the connection and deploy shape. For tuning, failure modes, and local development, see the [Trino engine manual](https://v2.dataos.info/references/engine-guide/trino-1/dedicated-cluster) in References.

## How it works

One vulcan trino resource creates 5 cooperating resources:

```
<name>-trino           Trino coordinator (replicas: 1)
<name>-trino-workers   Trino workers
<name>-plan            vulcan migrate, then plan --auto-apply (waits for the cluster)
<name>-run             vulcan run (scheduled; depends on plan)
<name>-api             Vulcan API for consumers
```

Check their status with:

```bash
dataos-ctl resource -t vulcan -n <name> get runtime -r
```

Vulcan generates catalogs automatically: one per depot in `deployment.depots[]`, plus one per secret catalog you define.

## Prerequisites

Request these from your platform team:

* A Trino-capable compute pool.
* The tenant-level `vulcan-trino` stack (`vulcan+trino:1.0`) installed.
* One depot per source you read. The first depot must be a writable lakehouse depot; it's the materialization target.
* Tenant secrets `vulcan-state-connection` (Postgres) and `vulcan-object-store-connection` (S3), and a git-sync secret for your repo.
* Python 3.10 to 3.13 locally for the Vulcan CLI.

Confirm your depots are visible with `dataos-ctl resource -t depot get -a`.

## Permissions

There are no Trino SQL grants to configure here: Vulcan connects to the internal coordinator over the Kubernetes network with `method: no-auth`. Access control lives entirely at each depot's underlying data source: whatever the depot's credentials permit there is what Trino can do through that catalog.

| Depot type   | Trino connector             | Permission guide                                                                                                                          |
| ------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `lakehouse`  | `iceberg` (REST)            | DataOS-native; no external grants                                                                                                         |
| `postgres`   | `postgresql`                | [Postgres minimum permissions](https://v2.dataos.info/references/resources/vulcan/roles-and-permissions/postgres-minimum-permissions)     |
| `snowflake`  | `snowflake`                 | [Snowflake minimum permissions](https://v2.dataos.info/references/resources/vulcan/roles-and-permissions/snowflake-minimum-permissions)   |
| `bigquery`   | `bigquery`                  | Governed by IAM roles on the depot's service account                                                                                      |
| `databricks` | `iceberg` (REST, read-only) | [Databricks minimum permissions](https://v2.dataos.info/references/resources/vulcan/roles-and-permissions/databricks-minimum-permissions) |
| `delta_lake` | `delta_lake`                | AWS IAM (S3 + Glue/Hive Metastore)                                                                                                        |

## config.yaml

The gateway catalog is templated from an environment variable the stack injects, so the same file works locally and in production:

```yaml
name: my-trino-dp
description: "Managed Trino data product."
gateways:
  default:
    connection:
      type: trino
      catalog: "{{ env_var('TRINO_CATALOG') }}"
default_gateway: default
model_defaults:
  dialect: trino
  start: <YYYY-MM-DD>
  cron: "@daily"
ignore_patterns:
  - "*-deploy.yaml"
```

{% hint style="info" %}
**Tenant can be set in config.yaml or via the environment**

`tenant` is a valid `config.yaml` key, and `domain` becomes required once `tenant` is set. Alternatively, set `DATAOS_TENANT_ID` in your shell for local runs; the platform injects it in production, where it overrides `tenant`. Vulcan refuses to load the project without a tenant set either way.
{% endhint %}

Cluster settings for this product live under `deployment.trino:` in this same file (see [The deploy configuration](#the-deploy-configuration) below). Keep `ignore_patterns: ["*-deploy.yaml"]` so that a rendered deploy manifest saved inside the project is never parsed as a model.

## Models: always use three-part names

Use fully-qualified `catalog.schema.name` for the model name and every source you read. The default catalog is the first secret catalog if any exist, otherwise the first depot. Unqualified names are a common cause of models materializing in the wrong place, so always spell out all 3 parts:

```sql
MODEL (
  name <lakehousedepot>.bronze.orders,
  kind FULL,
  grains (order_id),
  assertions (
    unique_values(columns := (order_id)),
    not_null(columns := (order_id, customer_id, order_date))
  )
);

SELECT order_id, customer_id, order_date, order_status
FROM <postgresdepot>.public.orders_ext;
```

## The deploy configuration

There's no separate manifest to hand-author for the Trino cluster. Coordinator and worker settings live under a `deployment.trino:` block, inside the same `config.yaml` you already have, alongside `deployment.repo`, `deployment.compute`, and the other keys every engine uses. See [References → Vulcan → Deployment](https://v2.dataos.info/references/resources/vulcan/deployment) for the full `deployment:` walkthrough; this section covers only the Trino-specific parts.

The fields you'll change most often are `deployment.depots` (order matters: the first one is the default catalog and write target), `deployment.trino.coordinator.resource`, and `deployment.trino.workers`:

```yaml
deployment:
  repo:
    url: <repo-url>
    base_dir: <path/to/project>
    secret_id: <tenant>:<git-sync-secret>
  compute: <trino-compute-pool>
  run_as_user: svc-user

  depots:
    - dataos://<lakehousedepot>?purpose=rw   # default catalog and write target
    - dataos://<postgresdepot>?purpose=rw    # source

  trino:
    catalog:
      config: [ "<tenant>:<catalog-secret>" ]   # optional secret catalog; see note below
    coordinator:
      resource:
        request: { cpu: "1", memory: 2Gi }
        limit:   { cpu: "2", memory: 4Gi }
    workers:
      replicas: 1
      resource:
        request: { cpu: "2", memory: 4Gi }

  use:
    env_vars:
      - key: TRINO_CATALOG
        template: "<lakehousedepot>"
```

Size `coordinator.resource` and `workers.resource` to fit the compute pool; an undersized coordinator or worker limit is the most common deployment failure. `TRINO_CATALOG` must match a real catalog name.

Each `deployment.trino.catalog.config` entry is a `"<tenant>:<secret-name>"` reference to a DataOS secret whose key/value pairs are Trino catalog properties; the secret name becomes the catalog name. Secret catalogs take priority over depot catalogs as the default catalog, which is why the example pins `TRINO_CATALOG` to the lakehouse depot. Omit `catalog` if every source has a depot.

{% hint style="danger" %}
Cluster autoscaling is not actually available: the deployment accepts `workers.autoscale` settings but does not render them. Set a fixed worker count with `workers.replicas` instead, and add workers manually for more query parallelism.
{% endhint %}

Set the JVM heap explicitly for both coordinator and workers, sized to the pod memory limit — an unmanaged heap is the most common cause of workers that OOM or never register. `4G` is the validated `-Xmx` for a `4Gi` pod limit; size yours to your own. If Postgres is the gateway catalog, set `register_comments: false` on the connection — the Postgres connector rejects the DDL Vulcan uses to register column comments.

{% hint style="warning" %}
**`deployment.trino` is engine-gated**

`deployment.trino` is only valid when the resolved `engine` is `trino` (derived from the gateway `connection.type`, as here, or from `model_defaults.dialect`). Setting it under any other engine fails validation at `vulcan create_deploy_yaml` time, before anything reaches DataOS.
{% endhint %}

## Local development

Local development runs a real Trino coordinator and worker via Docker Compose (mounted at `/usr/lib/trino/etc`, Trino's real config path — a different mount path fails silently), plus a local Postgres container Trino federates against. Point `config.yaml` at the local coordinator (`host: localhost`, `method: no-auth`) with a DuckDB `state_connection`, add `ignore_patterns: ["*-deploy.yaml"]` so the deploy manifest is never parsed as a model, then validate with `vulcan migrate && vulcan plan && vulcan run`. See the [Trino engine manual](https://v2.dataos.info/references/engine-guide/trino-1/dedicated-cluster) for the full Docker Compose setup.

## Troubleshooting

| Symptom                                               | Likely cause                                                   | Fix                                                                              |
| ----------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Cluster forms with 0 workers / workers OOM at startup | Unmanaged JVM heap exceeds pod limit                           | Set `-Xmx` to fit the pod limit for both coordinator and workers.                |
| Workers never register / cluster won't form           | `node.environment` mismatch, or `coordinator=true` on a worker | Make `node.environment` identical on both roles; never set `node.id` on workers. |
| Custom plugin/UDF not loaded                          | JAR at `dependencies/java/` root, not in a subdirectory        | Move it into `dependencies/java/<plugin>/`.                                      |
| Postgres catalog: `vulcan plan` fails on comment DDL  | `register_comments` not disabled                               | Set `register_comments: false` on the gateway connection.                        |

For the full failure-mode table, recovery procedures, and log locations, see [Troubleshooting](https://v2.dataos.info/references/engine-guide/trino-1/dedicated-cluster) in the Trino engine manual.

## Apply and verify

Deploying a dedicated Trino product uses the same single flow as every other engine: render the manifest from `config.yaml` and apply it; no separate `dataos-ctl resource apply -f trino-deploy.yaml` step is required.

```bash
vulcan create_deploy_yaml -o - | dataos-ctl resource apply --in -l   # lint first
vulcan create_deploy_yaml -o - | dataos-ctl resource apply --in      # then apply
dataos-ctl resource -t vulcan -n my-trino-dp get -r
```

Confirm the cluster is up by looking for `SERVER STARTED` in the coordinator logs. The [Trino engine manual](https://v2.dataos.info/references/engine-guide/trino-1/dedicated-cluster) covers common issues (workers out of memory, wrong-catalog materialization, schedules expiring silently) and their fixes.

With the cluster running, continue to [Assets](https://v2.dataos.info/build/productize/assets.md).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/build/productize/connect-engine/trino/dedicated-trino.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
