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.
Optional options: nullish | DataAPIClientOptionsThe default options to use when spawning new instances of Db or AstraAdmin.
const client = new DataAPIClient();
// OK
const db1 = client.db('<db_id>', '<region>', { token: 'AstraCS:...' });
// Will throw error as no token is ever provided
const db2 = client.db('<db_id>', '<region>');
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.
The default token to use when spawning new instances of Db or AstraAdmin.
Optional options: nullish | DataAPIClientOptionsThe default options to use when spawning new instances of Db or AstraAdmin.
const client = new DataAPIClient('<default_token>');
// OK
const db1 = client.db('<db_id>', '<region>', { token: '<weaker_token>' });
// OK; will use <default_token>
const db2 = client.db('<db_id>', '<region>');
Private Readonly #optionsAllows for the await using syntax (if your typescript version >= 5.2) to automatically close the client when
it's out of scope.
Equivalent to wrapping the client usage in a try/finally block and calling client.close() in the finally
block.
async function main() {
// Will unconditionally close the client when the function exits
await using client = new DataAPIClient('*TOKEN*');
// Using the client as normal
const db = client.db('*ENDPOINT*');
console.log(await db.listCollections());
// Or pass it to another function to run your app
app(client);
}
main();
This will only be defined if the Symbol.asyncDispose symbol is actually defined.
Spawns a new AstraAdmin instance using the given options to work with the DevOps API (for admin work such as creating/managing databases).
NB. This method is only available for Astra databases.
The given options will override any default options set when creating the DataAPIClient through a deep merge (i.e. unset properties in the options object will just default to the default options).
Optional options: AdminSpawnOptionsAny options to override the default options set when creating the DataAPIClient.
A new AstraAdmin instance.
const admin1 = client.admin();
const admin2 = client.admin({ adminToken: '<stronger_token>' });
const dbs = await admin1.listDatabases();
console.log(dbs);
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.
A promise that resolves when the client has been closed.
This method is idempotent and can be called multiple times without issue.
--
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 always strictly necessary for long-running usages, but it's there for when you need it.
Spawns a new Db instance using a direct endpoint and given options.
NB. This method does not validate the existence of the database—it simply creates a reference.
This endpoint should include the protocol and the hostname, but not the path. It's typically in the form of
https://<db_id>-<region>.apps.astra.datastax.com, but it can be used with DSE or any other Data-API-compatible
endpoint.
The given options will override any default options set when creating the DataAPIClient through a deep merge (i.e. unset properties in the options object will just default to the default options).
The direct endpoint to use.
Optional options: DbSpawnOptionsAny options to override the default options set when creating the DataAPIClient.
A new Db instance.
const db1 = client.db('https://<db_id>-<region>.apps.astra.datastax.com');
const db2 = client.db('https://<db_id>-<region>.apps.astra.datastax.com', {
namespace: 'my-namespace',
useHttp2: false,
});
const db3 = client.db('https://<db_id>-<region>.apps.astra.datastax.com', { token: 'AstraCS:...' });
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.
Spawns a new Db instance using a direct endpoint and given options.
NB. This method does not validate the existence of the database—it simply creates a reference.
This overload is purely for user convenience, but it only supports using Astra as the underlying database. For DSE or any other Data-API-compatible endpoint, use the other overload instead.
The given options will override any default options set when creating the DataAPIClient through a deep merge (i.e. unset properties in the options object will just default to the default options).
The database ID to use.
The region to use.
Optional options: DbSpawnOptionsAny options to override the default options set when creating the DataAPIClient.
A new Db instance.
const db1 = client.db('a6a1d8d6-31bc-4af8-be57-377566f345bf', 'us-east1');
const db2 = client.db('a6a1d8d6-31bc-4af8-be57-377566f345bf', 'us-east1', {
namespace: 'my-namespace',
useHttp2: false,
});
const db3 = client.db('a6a1d8d6-31bc-4af8-be57-377566f345bf', 'us-east1', { token: 'AstraCS:...' });
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.
Rest ...args: Parameters<DataAPIClientEvents[E]>
The main entrypoint into working with the Data API. It sits at the top of the conceptual hierarchy of the SDK.
The client may take in a default token, which can be overridden by a stronger/weaker token when spawning a new Db or AstraAdmin instance.
It also takes in a set of default options (see DataAPIClientOptions) that may also generally be overridden as necessary.
Depending on the Data API backend used, you may need to set the environment option to "dse", "hcd", etc. See DataAPIEnvironment for all possible backends. It defaults to "astra".
Example
See
DataAPIEnvironment