Trino Client - Configuration - Client Setup

Basic Authentication #

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { TrinoClient } from "@lakeql/trino-client"

const client = new TrinoClient({
  host: "https://trino.example.com",
  port: 8443,
  auth: {
    type: "basic",
    username: "analyst",
    password: "s3cr3t",
  },
  catalog: "hive",
  schema: "sales",
})

The username and password are Base64-encoded and sent as an Authorization: Basic ... header on every request.

Bearer Token Authentication #

1
2
3
4
5
6
7
8
9
10
11
12
13
import { TrinoClient } from "@lakeql/trino-client"

const client = new TrinoClient({
  host: "https://trino.example.com",
  port: 8443,
  auth: {
    type: "bearer",
    token: "eyJhbGciOiJSUzI1NiIs...",
  },
  catalog: "iceberg",
  source: "my-etl-service",
})

The token is sent as an Authorization: Bearer ... header.

Retry Configuration #

The client automatically retries on transient failures (HTTP 429, 500, 502, 503, 504 and network errors). Configure retry behavior via the retry option:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { TrinoClient } from "@lakeql/trino-client"

const client = new TrinoClient({
  host: "https://trino.example.com",
  port: 8443,
  auth: { type: "basic", username: "analyst", password: "secret" },
  catalog: "hive",
  retry: {
    maxRetries: 5,
    initialDelay: 500,
    maxDelay: 30000,
    backoffMultiplier: 2,
  },
})

Property	Type
maxRetries?	`number`
Maximum number of retry attempts. Default: `3`
initialDelay?	`number`
Initial delay between retries in ms. Default: `1000`
maxDelay?	`number`
Maximum delay between retries in ms. Default: `30000`
backoffMultiplier?	`number`
Multiplier for exponential backoff. Default: `2`
retryableStatusCodes?	`number[]`
HTTP status codes that trigger a retry. Default: `[429, 500, 502, 503, 504]`

Timeout #

Set a default timeout (in milliseconds) for all requests. If a request exceeds this duration, it will be aborted:

1
2
3
4
5
6
7
8
9
10
import { TrinoClient } from "@lakeql/trino-client"

const client = new TrinoClient({
  host: "https://trino.example.com",
  port: 8443,
  auth: { type: "basic", username: "analyst", password: "secret" },
  catalog: "hive",
  timeout: 30_000, // 30 seconds
})

You can also pass a per-query signal for more fine-grained control — see Executing Queries.

Default Headers #

On construction, the client sets the following Trino headers automatically:

Header	Value
`X-Trino-Source`	The `source` option, or `"nodejs"` if omitted
`X-Trino-Catalog`	The `catalog` option
`X-Trino-Schema`	The `schema` option (only if provided)

You can modify headers after construction using setHeader() or setRawHeader():

1
2
3
client.setHeader("X-Trino-Schema", "production")
client.setRawHeader("X-Custom-Header", "value")