Trino Connection

Connection Configuration #

LakeQL connects to Trino via its REST API. Both the CLI (for introspection) and the API server (for query execution) use the same connection settings.

Basic Auth #

The default authentication method uses username and password, sent as HTTP Basic Auth:

1
2
3
4
5
HIVE_HOST="https://trino.example.com"
HIVE_PORT=8446
HIVE_USERNAME="my-user"
HIVE_PASSWORD="my-password"

These credentials are included in every request to Trino as Basic Authentication headers.

Bearer Auth #

For environments that use token-based authentication (e.g. OAuth2 access tokens), configure the Trino client to send a Bearer token instead. This is handled at the system user level for write operations where the API impersonates a service account.

Host and Port #

The full Trino endpoint is constructed as ${HIVE_HOST}:${HIVE_PORT}/v1/statement.

Default Catalog and Schema #

1
2
HIVE_CATALOG=hive

The HIVE_CATALOG variable sets the default catalog context. This is used:

• By the CLI when no --catalog flag is provided
• By the API server as the default catalog for generated queries
• In the X-Trino-Catalog session header

Source Header #

1
2
HIVE_SOURCE="lakeql"

The optional HIVE_SOURCE variable sets the X-Trino-Source header, which identifies the application in Trino's query logs. Useful for monitoring and debugging which system submitted a given query.

Connection in Code #

The Trino client is configured internally using these environment variables:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import Bourne from "@hapi/bourne"
import got from "got"

// The client sends requests to Trino's statement endpoint
const endpoint = `${env.HIVE_HOST}:${env.HIVE_PORT}/v1/statement`

// Requests include authentication and session headers
const headers = {
  "X-Trino-User": env.HIVE_USERNAME,
  "X-Trino-Source": env.HIVE_SOURCE ?? "lakeql",
  "X-Trino-Catalog": env.HIVE_CATALOG,
  Authorization: `Basic ${btoa(`${env.HIVE_USERNAME}:${env.HIVE_PASSWORD}`)}`,
}

Query Execution Flow #

When the API server submits a query to Trino:

1. POST the SQL statement to /v1/statement
2. Trino returns a response with a nextUri if results aren't ready yet
3. The client polls the nextUri until the query completes
4. Final response contains column metadata and row data as arrays

Troubleshooting #