{"id":16249,"library":"trino-client","title":"Trino JavaScript Client","description":"The `trino-client` library provides an official JavaScript/TypeScript client for interacting with Trino (formerly PrestoSQL) instances from Node.js environments. It enables developers to execute SQL queries, retrieve results, and manage connections programmatically. The current stable version is 0.2.9, with new releases occurring frequently, typically on a monthly or bi-monthly basis, primarily for dependency updates and minor improvements. A key differentiator introduced in version 0.2.0 is the adoption of async iterators for query results, offering an efficient and modern way to process potentially large datasets streamingly. The library supports secure connections via SSL/TLS and provides robust error handling for Trino interactions.","status":"active","version":"0.2.9","language":"javascript","source_language":"en","source_url":"https://github.com/trinodb/trino-js-client","tags":["javascript","trino","trinodb","client","typescript"],"install":[{"cmd":"npm install trino-client","lang":"bash","label":"npm"},{"cmd":"yarn add trino-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add trino-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for making HTTP requests to the Trino server.","package":"axios","optional":false},{"reason":"Used for handling multipart form data, potentially for specific Trino APIs or authentication methods.","package":"form-data","optional":false},{"reason":"Manages concurrency for requests.","package":"p-queue","optional":false}],"imports":[{"note":"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()`.","wrong":"const TrinoClient = require('trino-client').TrinoClient;","symbol":"TrinoClient","correct":"import { TrinoClient } from 'trino-client';"},{"note":"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.","wrong":"import { Trino } from 'trino-client';","symbol":"Trino","correct":"import type { Trino } from 'trino-client';"},{"note":"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.","wrong":"import { QueryConfig } from 'trino-client';","symbol":"QueryConfig","correct":"import type { QueryConfig } from 'trino-client';"}],"quickstart":{"code":"import { TrinoClient, type QueryConfig, type Trino } from 'trino-client';\n\nasync function runTrinoQuery() {\n  const config: QueryConfig = {\n    serverUrl: process.env.TRINO_SERVER_URL || 'http://localhost:8080',\n    catalog: process.env.TRINO_CATALOG || 'memory',\n    schema: process.env.TRINO_SCHEMA || 'default',\n    user: process.env.TRINO_USER || 'testuser',\n    // Optional: For SSL/TLS connections, enable 'https' and manage 'requestVerification'\n    // https: true,\n    // requestVerification: false // Use with caution for self-signed certs in dev\n    // For Basic Authentication, pass an 'auth' object, e.g.,\n    // auth: new (await import('trino-client')).BasicAuth('username', 'password'),\n  };\n\n  let trinoClient: Trino; // Type for the client instance\n\n  try {\n    // Starting from v0.2.0, TrinoClient constructor is private. Use static factory method.\n    trinoClient = TrinoClient.create(config);\n    console.log(`Connected to Trino at ${config.serverUrl}`);\n\n    const query = 'SELECT * FROM system.runtime.nodes LIMIT 1';\n    console.log(`Executing query: \"${query}\"`);\n\n    // The query method now returns an async iterator (since v0.2.0)\n    const queryResults = await trinoClient.query(query);\n\n    console.log('Query results:');\n    for await (const { columns, data } of queryResults) {\n      if (columns) {\n        console.log('Columns:', columns.map(c => c.name).join(', '));\n      }\n      if (data) {\n        data.forEach(row => console.log(row));\n      }\n    }\n    console.log('Query finished successfully.');\n\n  } catch (error) {\n    console.error('Failed to run Trino query:', error instanceof Error ? error.message : String(error));\n  }\n}\n\nrunTrinoQuery();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Use the static factory method `TrinoClient.create(config)` to obtain a client instance.","message":"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.","severity":"breaking","affected_versions":">=0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.2.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Use the static factory method `TrinoClient.create(config)` instead of `new TrinoClient(config)`.","cause":"Attempting to instantiate `TrinoClient` with the `new` keyword after version 0.2.0.","error":"TypeError: TrinoClient is not a constructor"},{"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).","cause":"Connecting to a Trino server over HTTPS with a self-signed or untrusted SSL/TLS certificate without disabling certificate verification.","error":"Error: self-signed certificate in certificate chain"},{"fix":"Ensure your environment is configured for ES modules and use `import { TrinoClient } from 'trino-client';`.","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.","error":"SyntaxError: Named export 'TrinoClient' not found"},{"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.","cause":"The specified catalog, schema, or table in your query does not exist, or the configured user lacks sufficient permissions to access it.","error":"Error: Query failed: line X:Y: Table 'catalog.schema.table' does not exist"}],"ecosystem":"npm"}