Connect with the Node.js driver

Because Astra DB is based on Apache Cassandra®, you can use Cassandra drivers to connect to your Astra DB Classic databases.

To use the Node.js driver, you need to install the driver and its dependencies, and then connect the driver to your Astra DB Classic database. Once connected, you can write scripts that use the driver to run commands against your database.

Prerequisites

Install Node.js LTS version with npm.
Create a database.
Download your database’s Secure Connect Bundle (SCB).

For multi-region databases, download the Secure Connect Bundle (SCB) for a region that is geographically close to your application to reduce latency.

If you need to connect to multiple regions in the same application, you need the Secure Connect Bundle (SCB) for each region, and your driver code must instantiate one root object (session) for each region. For more information, see Best practices for Cassandra drivers.
Set the following environment variables:
- ASTRA_DB_ID: The database ID.
- ASTRA_DB_KEYSPACE: A keyspace in your database, such as default_keyspace.
- ASTRA_DB_APPLICATION_TOKEN: An application token with the Database Administrator role.

Driver authentication methods

There are two driver authentication methods: token authentication, or clientId and secret authentication.

Token authentication
Client ID and secret authentication

This authentication method is supported and recommended for most recent driver versions.

In your driver authentication code, pass the literal string token as the username and your application token value (AstraCS:…) as the password. For example:

("token", "AstraCS:...")

If you are on an older driver version that doesn’t support token authentication, then you might need to use clientId and secret.

When you generate an application token, download or copy the token.json that contains the following values:

{
  "clientId": "CLIENT_ID",
  "secret": "CLIENT_SECRET",
  "token": "APPLICATION_TOKEN"
}

In your driver authentication code, pass clientId as the username and secret as the password. For example:

("CLIENT_ID", "SECRET")

For more information, see Token details.

Install the Node.js driver

Install the Node.js driver:
```
npm install cassandra-driver
```
If you choose to install an earlier version, make sure you choose a version that is compatible with Astra DB. For more information, see Cassandra drivers supported by DataStax.

Connect the Node.js driver

In the root of your Node.js project, create a connect-database.js file:
```
cd nodejsProject
touch connect-database.js
```

Copy the following connection code into the connect-database.js file, and then replace PATH_TO_SCB with the absolute path to your database’s Secure Connect Bundle (SCB) (secure-connect-DATABASE_NAME.zip):

connect-database.js

const cassandra = require('cassandra-driver');

const cloud = { secureConnectBundle: "PATH_TO_SCB" };
const authProvider = new cassandra.auth.PlainTextAuthProvider('token', process.env['ASTRA_DB_APPLICATION_TOKEN']);
const client = new cassandra.Client({ cloud, authProvider });

async function run() {
    await client.connect();

    // Execute a query
    const rs = await client.execute('SELECT * FROM system.local');
    console.log(Hello from cluster: ${rs.first()['cluster_name']});

    await client.shutdown();
}

This code creates a Client instance to connect to your Astra DB database, runs a CQL query, and prints the output to the console.

Save and then run connect-database.js with the Node.js runtime:
```
node connect-database.js
```
The console output includes the cluster_name value from the system.local table.
Extend or modify this script to run other commands against your database or connect to other databases. For more information, see Node.js driver documentation and DataStax-compatible Cassandra drivers.

Connect the Node.js Cloud driver (deprecated)

The legacy Stargate APIs and their associated drivers are deprecated for Astra DB Classic as of September 2024, and end-of-life (EOL) is scheduled for the end of 2025. As EOL approaches, DataStax will provide migration information to support your transition to other options.

If you have questions or concerns, contact your account representative or DataStax Support.

Create a keyspace.
Create a table for your keyspace.

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

npm
Yarn

npm i @stargate-oss/stargate-grpc-node-client

yarn add @stargate-oss/stargate-grpc-node-client

While running Stargate on Astra DB, generate a token for your database, and then add the token to the connection portion of the script.

The Bearer Token to use in the header of API calls is the same as your database’s application token, which is prefixed by AstraCS:, followed by a generated alphanumeric string.

// DB configuration
// replace with values from the Astra Portal
const astra_uri = "DATABASE_ID-REGION_NAME.apps.astra.datastax.com:443";
const bearer_token = "APPLICATION_TOKEN";

// Set up the authentication
// For Astra DB: Enter the database's application token for the bearer token
const bearerToken = new StargateBearerToken(bearer_token);
const credentials = grpc.credentials.combineChannelCredentials(
  grpc.credentials.createSsl(), bearerToken);

// Uncomment if you need to check the credentials
//console.log(credentials);

For a connection to a remote Stargate instance, like Astra DB, automatically generate on every call to the client:

// Create the gRPC client
// For Astra DB: passing the credentials created above
const stargateClient = new StargateClient(astra_uri, credentials);

console.log("made client");

// Create a promisified version of the client, so we don't need to use callbacks
const promisifiedClient = promisifyStargateClient(stargateClient);

console.log("promisified client")

Connect with the Node.js driver

Prerequisites

Driver authentication methods

Install the Node.js driver

Connect the Node.js driver

Connect the Node.js Cloud driver (deprecated)

See also

Was this helpful?

Give Feedback