Interface DbSpawnOptions

The options available spawning a new Db instance.

If any of these options are not provided, the client will use the default options provided by the DataAPIClient.

interface DbSpawnOptions {
    dataApiPath?: string;
    keyspace?: string;
    monitorCommands?: boolean;
    namespace?: string;
    token?: null | string | TokenProvider;
}

Properties

dataApiPath?: string

The path to the Data API, which is going to be api/json/v1 for all Astra instances. However, it may vary if you're using a different Data API-compatible endpoint.

Defaults to 'api/json/v1' if never provided. However, if it was provided when creating the DataAPIClient, it will default to that value instead.

Default Value

'api/json/v1'
keyspace?: string

The keyspace to use for the database.

There are a few rules for what the default keyspace will be:

  1. If a keyspace was provided when creating the DataAPIClient, it will default to that value.
  2. If using an astra database, it'll default to "default_keyspace".
  3. Otherwise, no default will be set, and it'll be on the user to provide one when necessary.

The client itself will not throw an error if an invalid keyspace (or even no keyspace at all) is provided—it'll let the Data API propagate the error itself.

Every db method will use this keyspace as the default keyspace, but they all allow you to override it in their options.

Example

const client = new DataAPIClient('AstraCS:...');

// Using 'default_keyspace' as the keyspace
const db1 = client.db('https://<db_id>-<region>.apps.astra.datastax.com');

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

// Finds 'my_collection' in 'default_keyspace'
const coll1 = db1.collection('my_collection');

// Finds 'my_collection' in 'my_keyspace'
const coll2 = db1.collection('my_collection');

// Finds 'my_collection' in 'other_keyspace'
const coll3 = db1.collection('my_collection', { keyspace: 'other_keyspace' });

Default Value

'default_keyspace'
monitorCommands?: boolean

Whether to monitor commands for Db-level & Collection-level events through an event emitter.

Defaults to false if never provided. However, if it was provided when creating the DataAPIClient, it will default to that value instead.

Example

const client = new DataAPIClient('*TOKEN*', {
  dbOptions: {
  monitorCommands: true,
  },
});

client.on('commandStarted', (event) => {
  console.log(`Running command ${event.commandName}`);
});

client.on('commandSucceeded', (event) => {
  console.log(`Command ${event.commandName} succeeded in ${event.duration}ms`);
});

client.on('commandFailed', (event) => {
  console.error(`Command ${event.commandName} failed w/ error ${event.error}`);
});

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

// Logs:
// - Running command insertOne
// - Command insertOne succeeded in <time>ms
await coll.insertOne({ name: 'Lordi' });

Default Value

false

See

DataAPICommandEvents

namespace?: string

The keyspace to use for the database.

This is now a deprecated alias for the strictly equivalent DbSpawnOptions.keyspace, and will be removed in an upcoming major version.

https://docs.datastax.com/en/astra-db-serverless/api-reference/client-versions.html#version-1-5

Deprecated

token?: null | string | TokenProvider

The access token for the Data API, typically of the format 'AstraCS:...'.

If never provided, this will default to the token provided when creating the DataAPIClient.

Example

const client = new DataAPIClient('strong-token');

// Using 'strong-token' as the token
const db1 = client.db('https://<db_id>-<region>.apps.astra.datastax.com');

// Using 'weaker-token' instead of 'strong-token'
const db2 = client.db('https://<db_id>-<region>.apps.astra.datastax.com', {
  token: 'weaker-token',
});