Class DataAPIClient

Overview

Constructs a new instance of the DataAPIClient without a default token. The token will instead need to be specified when calling .db() or .admin().

Prefer this method when using a db-scoped token instead of a more universal token.

Example

const client = new DataAPIClient();

// OK
const db1 = client.db('<endpoint>', { token: '<token>' });

// Will throw error as no token is ever provided
const db2 = client.db('<endpoint>');
Copy

Overview

Constructs a new instance of the DataAPIClient with a default token. This token will be used everywhere if no overriding token is provided in .db() or .admin().

Prefer this method when using a universal/admin-scoped token.

Example

const client = new DataAPIClient('<default_token>');

// OK
const db1 = client.db('<endpoint>', { token: '<weaker_token>' });

// OK; will use <default_token>
const db2 = client.db('<endpoint>');
Copy

Overview (Astra-only)

Spawns a new AstraAdmin instance using the given options to work with the DevOps API (for admin work such as creating/managing databases).

Note: this method is only available for Astra databases.

Example

const admin1 = client.admin();
const admin2 = client.admin({ adminToken: '<stronger_token>' });

const dbs = await admin1.listDatabases();
console.log(dbs);
Copy

The options hierarchy

The options for the AstraAdmin instance are a deep merge of the options for the DataAPIClient and the options for the AstraAdmin itself.

Overview

Closes the client and disconnects all underlying connections. This should be called when the client is no longer needed to free up resources.

The client will be no longer usable after this method is called.

This method is idempotent and can be called multiple times without issue.

Example

const client = new DataAPIClient(...);
await client.close();

// Error: Can't make requests on a closed client
const coll = client.db(...).collection(...);
await coll.findOne();
Copy

When to call this method

For most users, this method isn't necessary to call, as resources will be freed up when the server is shut down or the process is killed.

However, it's useful in long-running processes or when you want to free up resources immediately.

Think of it as using malloc or using a file descriptor. Freeing them isn't strictly necessary when they're used for the duration of the program, but it's there for when you need it.

Overview

Spawns a new Db instance using a direct endpoint and given options.

Disclaimer

This method does not validate the existence of the database—it simply creates a reference.**

Note that this does not perform any I/O or validation on if the endpoint is valid or not. It's up to the user to ensure that the endpoint is correct. If you want to create an actual database, see AstraAdmin.createDatabase instead.

The API endpoint

This endpoint should include the protocol and the hostname, but not the path.

If you're using Astra, this will typically be of the form https://<db_id>-<region>.apps.astra.datastax.com (the exception being private endpoints); any other database may have a completely unique domain.

Spawning a db via just an ID and region is no longer supported in astra-db-ts 2.0+. Use the buildAstraEndpoint to create the endpoint if you need to.

Example

const db = client.db('https://<db_id>-<region>.apps.astra.datastax.com');
Copy

The options hierarchy

The options for the Db instance are a deep merge of the options for the DataAPIClient and the options for the Db itself.

Any options provided to DbOptions may generally also be overridden in any spawned classes' options (e.g. CollectionOptions).

Example

const db = client.db('https://<db_id>-<region>.apps.astra.datastax.com', {
  keyspace: 'my_keyspace',
  token: 'AstraCS:...',
});

const coll = db.collection('my_coll', {
  keyspace: 'other_keyspace',
});
Copy

Remarks

Note that this does not perform any IO or validation on if the endpoint is valid or not. It's up to the user to ensure that the endpoint is correct. If you want to create an actual database, see AstraAdmin.createDatabase instead.