> 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/references/engine-guide/trino/minerva.md).

# Minerva

Minerva is DataOS's shared, managed Trino-based query cluster. From Vulcan's point of view, Minerva is a normal Trino endpoint, so the connection uses `type: trino`. Unlike a dedicated cluster, the data product does not own Minerva: many data products can share one large central cluster, and the cluster is provisioned and managed by DataOS, not by your `vulcan` resource.

Use Minerva when you want to share central compute rather than run a cluster per data product. To run your own isolated cluster instead, see [Dedicated Trino](/references/engine-guide/trino/dedicated-trino.md). To connect to a non-DataOS Trino, Starburst, or self-hosted cluster, see [External Trino](/references/engine-guide/trino/external-trino.md). For the rules common to all three shapes, see the [Trino engine overview](/references/engine-guide/trino.md).

Use the [Connect engine → Minerva](https://v2.dataos.info/build/productize/connect-engine/trino/minerva) Build page for the quick steps.

## Core settings

| Setting                 | Value                                         |
| ----------------------- | --------------------------------------------- |
| Resource type           | `vulcan`                                      |
| Gateway connection type | `trino`                                       |
| Model dialect           | `trino`                                       |
| VDE                     | `false`                                       |
| Scheduler               | Local or built-in scheduler                   |
| `spec.trino` block      | Not used (Vulcan does not manage the cluster) |

Minerva uses `basic` (or JWT) authentication over `https`. Catalogs are already mounted on the cluster, so the materialization target is the configured gateway catalog. Do not set `vde: true`; Trino gateways must run in simple mode.

## Prerequisites

You need:

* A running Minerva cluster in your tenant.
* The Minerva cluster name (for example, `minervainfinity`).
* The Minerva host (for example, `tcp.<env-name>.dataos.cloud`).
* The Minerva port (commonly `7432`).
* Your DataOS user id and DataOS API key.
* Your tenant name.
* A catalog name (for example, `s3depot`).
* A DataOS secret holding the user id and a generated Minerva password.

### Check whether the cluster exists

```bash
dataos-ctl resource get -t minerva -a
dataos-ctl resource get -t minerva -n <minerva-cluster-name>
```

Use the cluster name in the password payload below.

### Example Minerva resource

The Minerva cluster itself is a `minerva` resource (typically owned by your platform team). Its `depots` list controls which DataOS depots the cluster can access:

```yaml
version: v1alpha
type: minerva
name: ${MINERVA_CLUSTER_NAME}
tags:
  - minerva
spec:
  coordinator:
    replicas: 1
    envs:
      JVM__opts: "--add-opens=java.base/java.nio=ALL-UNNAMED"
    resources:
      requests: { cpu: "1", memory: "1Gi" }
      limits:   { cpu: "2", memory: "4Gi" }
  worker:
    replicas: 2
    envs:
      # Add -Dnet.snowflake.jdbc.enableBouncyCastle=TRUE if a Snowflake depot is referenced.
      JVM__opts: "--add-opens=java.base/java.nio=ALL-UNNAMED"
    resources:
      requests: { cpu: "1", memory: "1Gi" }
      limits:   { cpu: "2", memory: "4Gi" }
  compute: ${MINERVA_COMPUTE_NAME}
  depots:
    - address: "dataos://postgres?purpose=rw"
```

## Generate the Minerva password

The Minerva password is a base64-encoded JSON object with three fields.

| Field     | Meaning                      |
| --------- | ---------------------------- |
| `cluster` | Minerva cluster name.        |
| `apikey`  | DataOS API key for the user. |
| `tenant`  | DataOS tenant name.          |

On macOS or Linux:

```bash
echo -n '{"cluster":"<minerva-cluster-name>","apikey":"<dataos-api-key>","tenant":"<tenant-name>"}' | base64 | tr -d '\n'
```

On Windows PowerShell:

```powershell
$json = '{"cluster":"<minerva-cluster-name>","apikey":"<dataos-api-key>","tenant":"<tenant-name>"}'
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($json))
```

Use the generated value as `PASSWORD` in the DataOS secret.

## Minerva secret

Store only authentication values in the secret:

```yaml
name: trino-connection-secret
version: v2alpha
type: secret
layer: user
secret:
  type: key-value
  data:
    USER_ID: "<dataos-user-id>"
    PASSWORD: "<base64-json-password>"
```

Apply and verify it:

```bash
dataos-ctl resource apply -f trino-connection-secret.yaml
dataos-ctl resource get -t secret -n trino-connection-secret
```

## Project the secret into Vulcan

Project `USER_ID` and `PASSWORD` into the environment variables that `config.yaml` reads:

```yaml
use:
  projection:
    secrets:
      - contextAlias: trn
        id: <tenant>:trino-connection-secret
    projections:
      envVars:
        - key: TRINO_USER
          template: "{{ secrets['trn'].USER_ID | base64_decode }}"
        - key: TRINO_PASSWORD
          template: "{{ secrets['trn'].PASSWORD | base64_decode }}"
```

## config.yaml

```yaml
vde: false

gateways:
  default:
    connection:
      type: trino
      host: "tcp.<env-name>.dataos.cloud"
      port: 7432
      user: "{{ env_var('TRINO_USER') }}"
      catalog: "s3depot"
      http_scheme: https
      method: basic
      password: "{{ env_var('TRINO_PASSWORD') }}"
      verify: true

default_gateway: default

model_defaults:
  dialect: trino
  start: "2024-01-01"

ignore_patterns:
  - "*-deploy.yaml"
```

## Deploy resource

Because the cluster is managed by DataOS, the data product is a plain `vulcan` resource (no `spec.trino` block) that projects the connection from the secret:

```yaml
version: v1alpha
type: vulcan
name: trino-minerva
spec:
  runAsUser: "<owner>"
  compute: <trino-compute-pool>
  engine: trino
  repo:
    url: https://bitbucket.org/rubik_/vulcan-examples
    syncFlags: ["--ref=main", "--submodules=off"]
    baseDir: vulcan-examples/trino/trino-minerva
    secret: engineering:git-sync-rr
  use:
    projection:
      secrets:
        - id: engineering:trino-minerva-sec
          contextAlias: tmsh
      projections:
        envVars:
          - { key: TRINO_HOST,        template: "{{ secrets['tmsh'].TRINO_HOST | base64_decode }}" }
          - { key: TRINO_PORT,        template: "{{ secrets['tmsh'].TRINO_PORT | base64_decode }}" }
          - { key: TRINO_USER,        template: "{{ secrets['tmsh'].TRINO_USER | base64_decode }}" }
          - { key: TRINO_CATALOG,     template: "{{ secrets['tmsh'].TRINO_CATALOG | base64_decode }}" }
          - { key: TRINO_HTTP_SCHEME, template: "{{ secrets['tmsh'].TRINO_HTTP_SCHEME | base64_decode }}" }
          - { key: TRINO_METHOD,      template: "{{ secrets['tmsh'].TRINO_METHOD | base64_decode }}" }
          - { key: TRINO_PASSWORD,    template: "{{ secrets['tmsh'].TRINO_PASSWORD | base64_decode }}" }
  workflow:
    schedule:
      crons: ["0 */6 * * *"]
      endOn: "2027-01-01T00:00:00-00:00"
      timezone: "UTC"
      concurrencyPolicy: Forbid
    plan:   { command: [vulcan], arguments: ["plan", "-vv", "--auto-apply"] }
    run:    { command: [vulcan], arguments: ["run"] }
  api:
    replicas: 1
    resource:
      request: { cpu: "250m", memory: "512Mi" }
      limit:   { cpu: "1000m", memory: "2Gi" }
```

## Materialisation, models, and identifier casing

Minerva uses the same model, semantic, metric, and DQ code as any Trino-backed Vulcan project. Supported model kinds are `VIEW`, `FULL`, `SEED`, `INCREMENTAL_BY_TIME_RANGE`, and `INCREMENTAL_BY_PARTITION`. Identifiers are lowercase (quote with `"` only on reserved-word collisions), use fully qualified `catalog.schema.table` names, and prefer `TIMESTAMP(6)` for Iceberg-backed columns. The materialization target is the configured gateway catalog, and the Trino user must be able to create schemas, tables, and views in that catalog. For the full model, semantic, DQ, and endpoint behaviour shared across shapes, see the [Trino engine overview](/references/engine-guide/trino.md).

## Quick checklist

Before running `vulcan plan`, confirm:

* `vde: false` is set.
* `connection.type` is `trino` and `model_defaults.dialect` is `trino`.
* Minerva host, port, user, catalog, and password are configured.
* The DataOS secret is applied and projected into runtime environment variables.
* The Trino user can create schemas, tables, and views in the target catalog.

## Related

* [Connect engine → Minerva](https://v2.dataos.info/build/productize/connect-engine/trino/minerva) for the quick steps.
* [Trino engine overview](/references/engine-guide/trino.md) for the common rules and shared behaviour.
* [Dedicated Trino](/references/engine-guide/trino/dedicated-trino.md) and [External Trino](/references/engine-guide/trino/external-trino.md) for the other deployment shapes.


---

# 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://v2.dataos.info/references/engine-guide/trino/minerva.md?ask=<question>&goal=<endgoal>
```

`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.