trino-js-client

A Trino client for Node.js.

Join us on Trino Slack in #core-dev to discuss and help this project.

Features

• Connections over HTTP or HTTPS
• Supports HTTP Basic Authentication
• Per-query user information for access control

Requirements

• Node 24 or newer. This is what the tests run against, and what the engines field in package.json declares. The build and lint checks also run against Node 26, which becomes the active long term support release on 2026-10-28. Older versions may still work, but are not tested, and package managers that enforce engines refuse to install on them.
• Trino. The tests run against the latest public release, and against Trino 440 as an older reference point. Releases in between and since are very likely to work, because the client speaks the Trino client REST API, which changes rarely.

Install

npm install @trinodb/trino-js-client or yarn add @trinodb/trino-js-client

Versions up to and including 0.2.9 were published as trino-client, without a scope. The scoped name starts at 0.3.0. Update the dependency name to keep receiving new releases.

Usage

For additional info on all available methods and types have a look at the API documentation.

Create a Trino client

const trino: Trino = Trino.create({
  server: 'http://localhost:8080',
  catalog: 'tpcds',
  schema: 'sf100000',
  auth: new BasicAuth('test'),
});

Submit a query

const iter: Iterator<QueryResult> = await trino.query(
  'select * from customer limit 100'
);

Iterate through the query results

for await (const queryResult of iter) {
  console.log(queryResult.data);
}

Alternative: map and aggregate the data

const data: QueryData[] = await iter
  .map(r => r.data ?? [])
  .fold<QueryData[]>([], (row, acc) => [...acc, ...row]);

Examples

More usage examples can be found in the integration tests.

Projects using this client

The following projects use this client to talk to Trino. They are a good place to see it applied to a real workload, beyond the examples in this repository, so each entry links to the code that calls the client.

• Lightdash — business intelligence and analytics, using the client as its Trino warehouse connector. TrinoWarehouseClient.ts
• Malloy — an open source language for describing data relationships and transformations, in its Trino dialect connector. packages/malloy-db-trino
• Beekeeper Studio — a cross-platform SQL client and database manager. trino.ts
• DBCode — a database editor for Visual Studio Code, Cursor, and Windsurf. The extension source is not published, so only the manifest is public. dbcodeio/public
• DBeagle — a Visual Studio Code extension for SQL exploration. src/drivers/trino
• SQL Notebook Pro — a Visual Studio Code extension for SQL notebooks. src/driver.ts
• n8n-nodes-trino — a community node that queries Trino from an n8n workflow. nodes/Trino

Using the client in your own project? Open a pull request and add it to the list.

Build

Use the following commands to build the project locally with your modifications, and in preparation to contribute a pull request.

Requirements:

• yarn

Install dependencies:

yarn install --frozen-lockfile

Lint the source code:

yarn test:lint

Check formatting:

yarn prettier:check

Reformat anything it reports:

yarn prettier:format

Build:

yarn build

A successful build run does not produce any message on the terminal.

All three run together with yarn check, which is what the build workflow does. The formatting check is enforced there, so a pull request that has not been formatted fails before it is reviewed.

The Prettier configuration is shared with the other Trino JavaScript codebases, trino-query-ui and both web UIs in trino, and so is the choice to check only the TypeScript sources. Change it in all of them or in none.

Integration test

Integration tests run against a Trino server running on your workstation.

Requirements:

• kind
• kubectl

Create a cluster:

kind create cluster

Deploy Trino:

kubectl apply -f tests/it/trino.yml

Wait for pods to be ready:

kubectl wait --for=condition=ready pods -n trino-system --all --timeout=120s

Ensure Trino is running and available on port 8080. Run the following command in a separate terminal:

kubectl -n trino-system port-forward svc/trino 8080:8080

Run tests:

yarn test:it --testTimeout=60000

Output should look similar to the following:

 PASS  tests/it/client.spec.ts
  trino
    ✓ exhaust query results (1567 ms)
    ✓ close running query (200 ms)
    ✓ cancel running query (17 ms)
    ✓ get query info (1 ms)
    ✓ client extra header propagation
    ✓ query request header propagation (88 ms)
    ✓ QueryResult has error info
    ✓ QueryInfo has failure info (1 ms)
    ✓ prepare statement (98 ms)
    ✓ multiple prepare statement (432 ms)

Test Suites: 1 passed, 1 total
Tests:       10 passed, 10 total
Snapshots:   0 total
Time:        3.457 s
Ran all test suites matching /tests\/it/i.

Remove the cluster:

kind delete cluster

Contributing

Follow the Trino contribution guidelines and contact us on Slack and GitHub.

Copyright Trino JS Client contributors 2022-present

Versioning

From 1.0.0 onward every release increments the major version. Version 1.0.0 is followed by 2.0.0, then 3.0.0, with no compatibility implied between them. The scheme mirrors the way Trino itself numbers releases, and it sets the expectation that each version is its own upgrade. Read the release notes rather than the version number to find out what changed.

Releases before 1.0.0 used ordinary semantic versioning, and versions up to and including 0.2.9 were published under the unscoped name trino-client.

Releasing

Releases are fully automated with GitHub Actions. A release needs nothing beyond a merged pull request that updates the version.

1. Update the version field in package.json to the version you are about to release. Nothing else needs to change, since the lockfile records the workspace as 0.0.0-use.local rather than the released version.
2. Commit the change on a branch, using Release @trinodb/trino-js-client <version> as the commit message, and open a pull request.
3. Merge the pull request once it is approved and the checks pass.

Merging runs the release workflow, which compares the version in package.json against the preceding commit. When the version changed, the workflow publishes the package to npm and then creates a GitHub release, tagged with the version prefixed with v, and with generated release notes. A merge that leaves the version untouched publishes nothing.

Watch the run to confirm that it succeeds, and check that the new version appears on npm.

Publishing uses npm trusted publishing with OpenID Connect, so no npm token is stored in this repository. npm verifies the identity of the workflow directly and attaches a provenance attestation to every published version. The trusted publisher is configured in the package settings on npmjs.com and must match this repository and the release.yml workflow file name. Renaming that file breaks publishing until the configuration is updated to match.

Publishing a package under a name that does not exist on npm yet is the one case this does not cover, because trusted publishing attaches its configuration to an existing package. The first version under a new name has to be published by a maintainer with access to the @trinodb scope, with yarn npm publish --no-provenance, since provenance is only available from a supported continuous integration environment.