@trinodb/trino-js-client
    Preparing search index...

    @trinodb/trino-js-client

    trino-js-client

    A Trino client for Node.js.

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

    @latest it-tests license

    • Connections over HTTP or HTTPS
    • Supports HTTP Basic Authentication
    • Per-query user information for access control
    • 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.

    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.

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

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

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

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

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

    More usage examples can be found in the integration tests.

    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.

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

    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 tests run against a Trino server running on your workstation.

    Requirements:

    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

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

    Copyright Trino JS Client contributors 2022-present

    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.

    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.

    Settings
    Member Visibility

    On This Page
    trino-js-client