Connect with the Node.js driver

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

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

This quickstart explains how to use the Node.js driver to connect to an Astra Managed Clusters database and send some Cassandra Query Language (CQL) statements to the database. It also explains how to upgrade from an earlier version of the Node.js driver to a version that supports Astra DB.

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 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 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:
- DATABASE_ID: The database ID.
- APPLICATION_TOKEN: An application token with the Database Administrator role.

Driver authentication methods

There are two driver authentication methods:

token authentication

The token 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:...")

clientId and secret authentication

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"
}

Then, 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 install an earlier version of the driver, make sure your version is compatible with Astra DB. If you need to query vector data in Astra DB Serverless (vector) databases, make sure your version also supports vector data. 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.zip with the absolute path to your database’s Secure Connect Bundle (SCB) zip file (secure-connect-DATABASE_NAME.zip):
connect-database.js
```
const cassandra = require('cassandra-driver');

const cloud = { secureConnectBundle: "PATH/TO/SCB.zip" };
const authProvider = new cassandra.auth.PlainTextAuthProvider('token', process.env['APPLICATION_TOKEN']);
const client = new cassandra.Client({ cloud, authProvider });

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

    // ...

    await client.shutdown();
}
```
This code creates a Client instance to connect to your database. Use this instance to run CQL statements against your database, as demonstrated in the next step.
To test the connection, add a simple query to the script.

The following example queries the system.local table. You can replace the example SELECT statement with any CQL statement that you want to run against a keyspace and table in your database.
```
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();
}
```
Save and then run connect-database.js with the Node.js runtime:
```
node connect-database.js
```
If you ran the example SELECT statement on the system.local table, then the cluster_name value from the system.local table is printed to the console if the script runs successfully.

Upgrade the Node.js driver

Use these steps if you need to upgrade from an earlier version of the Node.js driver to a version that supports Astra DB:

Complete the prerequisites.
Install the latest Node.js driver.

In your existing DataStax Node.js driver code, modify the connection code to use the SCB and token authentication.

const { Client } = require('cassandra-driver');

const cloud = { secureConnectBundle: "PATH/TO/SCB.zip" };
const authProvider = new cassandra.auth.PlainTextAuthProvider('token', process.env['APPLICATION_TOKEN']);
const client = new cassandra.Client({ cloud, authProvider });

For more information, see Connect the Node.js driver.

Next steps

You can extend or modify the example script used in this guide to run other commands against your database, or connect to other databases. For more information, see the following: