Please leave your feedback with the Docs team.
Toggle Menu

Filter Results:

  • Astra DB
  • Astra Streaming
  • Luna Support
↓↑to navigate
↵to select
escto close
    powered by Apache Cassandra™
    Go to DataStax Home
    Dark Mode

    This client is designed for use with a Node.js application or backend.It is not intended for use with Javascript running in a browser environment.

    Prerequisites

    Install the package

    Install stargate-grpc-node-client using either npm or yarn :

    This set-up will make all the Stargate gRPC functionality available.

    The next sections explain the parts of a script to use the Stargate functionality.A full working script is included below.

    Node.js connecting

    Authentication

    This example assumes that you're running Stargate on Astra DB.For more information regarding authentication, see theManage application tokens section.

    You'll need to download your bearer token from the Astra DB dashboard andadd the token to the connection portion of the script.

    Creating a client

    For a connection to a remote Stargate instance like Astraautomatically generate on every call to the client:

    A simple query can be performed by passing a CQL query to the client using the`executeQuery()` function for standard query execution:

    Data definition (DDL) queries are supported in the same manner:

    Parameterized queries are also supported:

    If you would like to use abatch statement,the client also provides an `executeBatch()` function to execute a batch query:

    After executing a query, a response will be returned containing rows for a SELECT statement;otherwise the returned payload will be unset.The convenience function `ToResultSet()`` is provided to help transform this responseinto a ResultSet that's easier to work with.

    Reading primitive values

    Individual values from queries will be returned as a Value object.These objects have boolean `hasX()` methods, where X is the possible type of a value.

    There are corresponding `getX() methods on the Value` type that will return the value, if present.If the value does not represent type X, calling `getX()` will not return an error.You'll get undefined or another falsy value based on the expected data type.

    Reading CQL data types

    The built-in `toX()` methods for Values representing more complicated typeslike UUIDs can be hard to work with.This library exposes helper functions to translate a Value into a more easily used type:

    • toUUIDString
    • toCQLTime

    Unlike the built-in `toX()` methods, these helper functions will throw an error if the conversion fails.

    Here's an example of processing a UUID:

    To put all the pieces together, here is a sample script that combines all the piecesshown above:

    Getting started

    Clone the repo, then install dependencies:

    • 1
    Testing
    Running tests will require you have Docker installed on your machine;see their documentation for installationdetails based on your platform.
    Then run the tests:
    • 1
    These tests include an integration suite that usesthe Testcontainers libraryto spin up a Docker container running Stargate to test a gRPC connection and issues queries.
    See the integration tests at  src/client/client.test.ts  for more example uses of this client.
    Generating gRPC code stubs
    Should the Stargate protobuf files change and you need to generate new gRPC code,this project has an NPM script you can use:
    • 1
    After running, you will find the new generated `*grpc_pb.d.ts  and  *pb.d.ts files in  stargate-grpc-node-client/src/proto/`.
    TypeScript compilation
    This client is written in TypeScript but must compile JS for use in vanilla JavaScript environments.**If you change source code in this client, be sure to use the  npm run compile command after your changes to reflect them in the  lib  folder packaged for NPM consumers.**
    Testing changes locally
    You can use the yalc library to publishchanges to this client locally and test with a consuming application.Assuming you have `yalc` installed and you've already made your changes, do the following:
    • 1
    You may need to  rm -rf node_modules  and do a fresh  npm i  in the consuming application for the changes to take effect.
    Once you have this dependency established, you can update this client locallywith new changes at any time by running  yalc push  from the stargate-grpc-node-client  directory.
    Coding style
    This project uses  eslint  and  prettier  to lint and format code.These standards are enforced automatically with a husky pre-commit hook and in the CI pipeline.
    The Stargate gRPC Node.js Client repository is located athttps://github.com/stargate/stargate-grpc-node-client.
    • Jump to section: