Trino JavaScript Client

Common errors

• TypeError: TrinoClient is not a constructor

  cause Attempting to instantiate `TrinoClient` with the `new` keyword after version 0.2.0.
  fix Use the static factory method `TrinoClient.create(config)` instead of `new TrinoClient(config)`.

• Error: self-signed certificate in certificate chain

  cause Connecting to a Trino server over HTTPS with a self-signed or untrusted SSL/TLS certificate without disabling certificate verification.
  fix If in a development environment, set `requestVerification: false` in your `QueryConfig`. For production, ensure the Trino server uses a certificate issued by a trusted Certificate Authority (CA).

• SyntaxError: Named export 'TrinoClient' not found

  cause Trying to use CommonJS `require()` syntax (e.g., `const { TrinoClient } = require('trino-client');`) in a module that primarily uses ES modules, or an incorrect named import.
  fix Ensure your environment is configured for ES modules and use `import { TrinoClient } from 'trino-client';`.

• Error: Query failed: line X:Y: Table 'catalog.schema.table' does not exist

  cause The specified catalog, schema, or table in your query does not exist, or the configured user lacks sufficient permissions to access it.
  fix Verify the `catalog`, `schema`, `user`, and table name in your `QueryConfig` and SQL query. Check Trino server logs for more details on access rights or table existence.

Warnings

• breaking The `TrinoClient.query` method no longer returns a promise resolving to a single result object but an async iterator of result pages. Direct access to `columns` or `data` properties on the initial promise resolution will fail.
  Fix: Update query result consumption to use a `for await...of` loop to iterate over `QueryResult` objects. Each `QueryResult` object will contain `columns` and `data` for a specific page of results.
• breaking The `TrinoClient` class constructor was made private in v0.2.0. Instantiating via `new TrinoClient()` will result in a TypeError, as the constructor is no longer publicly accessible.
  Fix: Use the static factory method `TrinoClient.create(config)` to obtain a client instance.
• gotcha When connecting to Trino via HTTPS, ensure proper SSL/TLS configuration. Using `requestVerification: false` (equivalent to `rejectUnauthorized: false` in Node.js `https` module) disables certificate validation. This is a security risk and should only be used in development environments with self-signed certificates.
  Fix: For production, ensure your Trino server uses trusted certificates. If using self-signed certificates in development, explicitly set `https: true` and `requestVerification: false` in `QueryConfig`, understanding the security implications.

Install

• npm install trino-client npm
• yarn add trino-client yarn
• pnpm add trino-client pnpm

Imports

• TrinoClient
  wrong:

  const TrinoClient = require('trino-client').TrinoClient;

  correct:

  import { TrinoClient } from 'trino-client';

  The library primarily uses ES modules. While CommonJS `require` might work in some transpiled setups, `import` is the idiomatic and recommended approach. The `TrinoClient` class itself is not directly constructible since v0.2.0; use `TrinoClient.create()`.
• Trino
  wrong:

  import { Trino } from 'trino-client';

  correct:

  import type { Trino } from 'trino-client';

  This is typically used as a TypeScript type for the client instance returned by `TrinoClient.create()`, not a runtime value. Import it as a type.
• QueryConfig
  wrong:

  import { QueryConfig } from 'trino-client';

  correct:

  import type { QueryConfig } from 'trino-client';

  This interface defines the configuration options for connecting to Trino and executing queries. It's a TypeScript type and should be imported as such for type safety.

Quickstart

Demonstrates how to connect to a Trino instance, execute a simple `SELECT` query, and process results using the async iterator pattern. It includes basic configuration and handles environment variables for sensitive data.

import { TrinoClient, type QueryConfig, type Trino } from 'trino-client';

async function runTrinoQuery() {
  const config: QueryConfig = {
    serverUrl: process.env.TRINO_SERVER_URL || 'http://localhost:8080',
    catalog: process.env.TRINO_CATALOG || 'memory',
    schema: process.env.TRINO_SCHEMA || 'default',
    user: process.env.TRINO_USER || 'testuser',
    // Optional: For SSL/TLS connections, enable 'https' and manage 'requestVerification'
    // https: true,
    // requestVerification: false // Use with caution for self-signed certs in dev
    // For Basic Authentication, pass an 'auth' object, e.g.,
    // auth: new (await import('trino-client')).BasicAuth('username', 'password'),
  };

  let trinoClient: Trino; // Type for the client instance

  try {
    // Starting from v0.2.0, TrinoClient constructor is private. Use static factory method.
    trinoClient = TrinoClient.create(config);
    console.log(`Connected to Trino at ${config.serverUrl}`);

    const query = 'SELECT * FROM system.runtime.nodes LIMIT 1';
    console.log(`Executing query: "${query}"`);

    // The query method now returns an async iterator (since v0.2.0)
    const queryResults = await trinoClient.query(query);

    console.log('Query results:');
    for await (const { columns, data } of queryResults) {
      if (columns) {
        console.log('Columns:', columns.map(c => c.name).join(', '));
      }
      if (data) {
        data.forEach(row => console.log(row));
      }
    }
    console.log('Query finished successfully.');

  } catch (error) {
    console.error('Failed to run Trino query:', error instanceof Error ? error.message : String(error));
  }
}

runTrinoQuery();