Class AstraAdmin

Use DataAPIClient.admin to obtain an instance of this class.

Creates a new database with the given configuration.

NB. this is a long-running operation. See AdminBlockingOptions about such blocking operations. The default polling interval is 10 seconds. Expect it to take roughly 2 min to complete.

Note that the name field is non-unique and thus creating a database, even with the same options, is not idempotent.

You may also provide options for the implicit Db instance that will be created with the database, which 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).

See CreateDatabaseOptions for complete information about the options available for this operation.

Example

const newDbAdmin1 = await admin.createDatabase({
  name: 'my_database_1',
  cloudProvider: 'GCP',
  region: 'us-east1',
});

// Prints '[]' as there are no collections in the database yet
console.log(newDbAdmin1.db().listCollections());

const newDbAdmin2 = await admin.createDatabase({
  name: 'my_database_2',
  cloudProvider: 'GCP',
  region: 'us-east1',
  keyspace: 'my_keyspace',
}, {
  blocking: false,
  dbOptions: {
    useHttp2: false,
    token: '<weaker-token>',
  },
});

// Can't do much else as the database is still initializing
console.log(newDbAdmin2.db().id);
Copy

Remarks

Note that if you choose not to block, the returned AstraDbAdmin object will not be very useful until the operation completes, which is up to the caller to determine.

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

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).

Example

const admin = new DataAPIClient('token').admin();

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

const db2 = admin.db('https://<db_id>-<region>.apps.astra.datastax.com', {
  keyspace: 'my-keyspace',
  useHttp2: false,
});
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.

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

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).

Example

const admin = new DataAPIClient('token').admin();

const db1 = admin.db('a6a1d8d6-31bc-4af8-be57-377566f345bf', 'us-east1');

const db2 = admin.db('a6a1d8d6-31bc-4af8-be57-377566f345bf', 'us-east1', {
  keyspace: 'my-keyspace',
  useHttp2: false,
});
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.

Spawns a new AstraDbAdmin instance for a database using a direct endpoint and given options.

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 are for the underlying implicitly-created Db instance, not the AstraDbAdmin instance. The db admin will use the same options as this AstraAdmin instance.

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).

Example

const admin = new DataAPIClient('token').admin();

const dbAdmin1 = admin.dbAdmin('https://<db_id>-<region>...');

const dbAdmin2 = admin.dbAdmin('https://<db_id>-<region>...', {
  keyspace: 'my-keyspace',
  useHttp2: false,
});
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.

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

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 are for the underlying implicitly-created Db instance, not the AstraDbAdmin instance. The db admin will use the same options as this AstraAdmin instance.

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).

Example

const admin = new DataAPIClient('token').admin();

const dbAdmin1 = admin.dbAdmin('a6a1d8d6-...-377566f345bf', 'us-east1');

const dbAdmin2 = admin.dbAdmin('a6a1d8d6-...-377566f345bf', 'us-east1', {
  keyspace: 'my-keyspace',
  useHttp2: false,
});
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.

Fetches the complete information about the database, such as the database name, IDs, region, status, actions, and other metadata.

Example

const info = await admin.info('<db_id>');
console.log(info.info.name, info.creationTime);
Copy

Terminates a database by ID or by a given Db instance.

NB. this is a long-running operation. See AdminBlockingOptions about such blocking operations. The default polling interval is 10 seconds. Expect it to take roughly 6-7 min to complete.

The database info will still be accessible by ID, or by using the AstraAdmin.listDatabases method with the filter set to 'ALL' or 'TERMINATED'. However, all of its data will very much be lost.

Example

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

// Or just
await admin.dropDatabase('a6a1d8d6-31bc-4af8-be57-377566f345bf');
Copy

Remarks

Use with caution. Wear a harness. Don't say I didn't warn you.

Lists all databases in the current org/account, matching the optionally provided filter.

Note that this method is paginated, but the page size is high enough that most users won't need to worry about it. However, you can use the limit and skip options to control the number of results returned and the starting point for the results, as needed.

You can also filter by the database status using the include option, and by the database provider using the provider option.

See ListDatabasesOptions for complete information about the options available for this operation.

Example

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

const activeDbs = await admin.listDatabases({ include: 'ACTIVE' });

for (const db of activeDbs) {
  console.log(`Database ${db.name} is active`);
}
Copy