Databases reference

Databases are used to store collections in Astra DB Serverless.

Connect to a database

You must connect to a database before you can work with data.

  • Python

  • TypeScript

  • Java

  • cURL

  • CLI

View this topic in more detail on the API Reference.

Get a reference to an existing database using the default namespace.

database = client.get_database_by_api_endpoint("API_ENDPOINT")

The example above is equivalent to the following shorthand (where, additionally, a Database ID can be supplied as well):

database = client["API_ENDPOINT"]

Get a reference to an existing database using a specific namespace.

database = client.get_database_by_api_endpoint(
    "API_ENDPOINT",
    namespace="NAMESPACE",
)

An instance of the Database class always has a notion of working namespace. This can be passed explicitly, as in the second example below, or left to its system default of "default_keyspace". Some subsequent operations with the database will act on the working namespace, unless a different one is given in the method invocation: this holds for get_collection, create_collection, list_collection_names, list_collections and command.

Returns:

Database - An instance of the Database class.

Example response
Database(api_endpoint="https://01234567-89ab-cdef-0123-456789abcdef-us-east1.apps.astra.datastax.com", token="AstraCS:aAbB...", namespace="default_keyspace")

Parameters:

Name Type Summary

api_endpoint

str

The full "API Endpoint" string used to reach the Data API. Example: "https://<database_id>-<region>.apps.astra.datastax.com"

token

Optional[str]

If supplied, is passed to the Database instead of the client token.

namespace

Optional[str]

If provided, is passed to the Database (it is left to the default otherwise).

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")

database = my_client.get_database_by_api_endpoint("01234567-...")
collection = database.create_collection("movies", dimension=512)
collection.insert_one({"title": "The Title"}, vector=...)

View this topic in more detail on the API Reference.

Get a reference to an existing database using the default namespace.

const db = client.db('API_ENDPOINT');

Get a reference to an existing database using a specific namespace.

const db = client.db('API_ENDPOINT', { namespace: 'NAMESPACE' });

An instance of the Db class always has a notion of working namespace. This can be passed explicitly, as in the second example below, or left to its system default of 'default_keyspace'. Some subsequent operations with the database will act on the working namespace, unless a different one is given in the method invocation: this holds for collection, createCollection, dropCollection, listCollections, and command.

Parameters:

Name Type Summary

endpoint

string

The full "API Endpoint" string used to reach the Database on the Data API (typically of the format 'https://<database_id>-<region>.apps.astra.datastax.com')

options?

DbSpawnOptions

The options to use for the database (namespace can be overridden in method calls)

Options (DbSpawnOptions):

Note that if any of these options were set through the client, they act as the actual defaults for these options (e.g. setting the namespace in the client, so it’s automatically used for every spawned db).

Name Type Summary

namespace?

string

The namespace to use for the database. Defaults to 'default_keyspace'. Can be overridden in method calls.

monitorCommands?

boolean

Whether to monitor commands through CommandEvents, using the client as an event emitter. Defaults to false.

token?

string

Access token to use for the database. Default is the client’s token. Typically, of the form 'AstraCS:…​'.

dataApiPath?

string

Path to the Data API. Defaults to 'api/json/v1'.

Returns:

Db - An unverified reference to the database.

Example:

import { DataAPIClient } from '@datastax/astra-db-ts'

const client = new DataAPIClient('TOKEN');

// Connect to a database using a direct endpoint
const db1 = client.db('API_ENDPOINT');

// Overrides default options from the DataAPIClient
const db2 = client.db('API_ENDPOINT', {
  namespace: 'NAMESPACE',
  token: 'WEAKER_TOKEN',
});

// Lets you connect using a database ID and region
const db3 = client.db('DB_ID', 'REGION');

// Use the database
(async function () {
  const collection = db1.collection('movies');
  await collection.insertOne({ title: 'The Italian Job' }, { vector: [...] });
})();

Get a reference to an existing database. You can access the database from its endpoint (url) or a combination of identifier, cloud and region.

To get details on each signature you can access the DataAPIClient JavaDOC.

// Given 'client' an instance of 'DataAPIClient'
Database db1 = client.getDatabase(String apiEndpoint);
Database db2 = client.getDatabase(String apiEndpoint, String namespace);
Database db3 = client.getDatabase(UUID databaseId);
Database db4 = client.getDatabase(UUID databaseId, String namespace);
Database db5 = client.getDatabase(UUID databaseId, String namespace, String region);

An instance of the Database class always has a notion of working namespace. This can be passed explicitly, or left to its system default of "default_keyspace". Some subsequent operations with the database will act on the working namespace, unless a different one is given in the method invocation: this holds for the getCollection, createCollection, listCollectionNames, listCollections and runCommand.

Returns:

Database - An instance of the Database class.

Parameters:

Name Type Summary

apiEndpoint

String

The endpoint URL for the database.

namespace

String

The namespace to use. If not provided, the default is default_keyspace.

databaseId

UUID

The database identifier, the endpoint url will be built from it using the default region.

region

String

The region where database is deployed you want to contact. Useful in multi-regions configurations.

Example:

package com.datastax.astra.client;


import com.dtsx.astra.sdk.db.domain.CloudProviderType;

import java.util.UUID;

public class Connecting {
    public static void main(String[] args) {
        // Preferred Access with DataAPIClient (default options)
        DataAPIClient client = new DataAPIClient("TOKEN");

        // Overriding the default options
        DataAPIClient client1 = new DataAPIClient("TOKEN", DataAPIOptions
                .builder()
                .withHttpConnectTimeout(10)
                .withHttpRequestTimeout(10)
                .build());

        // Access the Database from its endpoint
        Database db1 = client1.getDatabase("API_ENDPOINT");
        Database db2 = client1.getDatabase("API_ENDPOINT", "NAMESPACE");

        // Access the Database from its endpoint
        UUID databaseId = UUID.fromString("f5abf92f-ff66-48a0-bbc2-d240bc25dc1f");
        Database db3 = client.getDatabase(databaseId);
        Database db4 = client.getDatabase(databaseId, "NAMESPACE");
        Database db5 = client.getDatabase(databaseId, "NAMESPACE", "us-east-2");

    }
}

Connect to a database by using the ASTRA_DB_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE endpoint.

Parameters:

Name Type Summary

ASTRA_DB_APPLICATION_TOKEN

string

The authentication token for Astra DB.

ASTRA_DB_ENDPOINT

string

The endpoint URL for the database.

ASTRA_DB_KEYSPACE

string

(Optional) The keyspace to use. If not provided, the default is default_keyspace.

Example:

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json"

The CLI gives you an overview of your database metadata.

astra db describe <database_name>
astra db describe <database_uid>

Arguments:

Options Type Description

database_name

String

The desired name for the database (does not ensure uniqueness).

database_uid

String

The desired identifier for the database.

Example response
+------------------+-----------------------------------------+
| Attribute        | Value                                   |
+------------------+-----------------------------------------+
| Name             | astra_db_client                         |
| id               | 4391daae-016c-49e3-8d0a-b4633a86082c    |
| Cloud            | GCP                                     |
| Regions          | us-east1                                |
| Status           | ACTIVE                                  |
| Vector           | Enabled                                 |
| Default Keyspace | default_keyspace                        |
| Creation Time    | 2024-02-24T01:20:03Z                    |
|                  |                                         |
| Keyspaces        | [0] default_keyspace                    |
|                  |                                         |
|                  |                                         |
| Regions          | [0] us-east1                            |
|                  |                                         |
+------------------+-----------------------------------------+

Create a database

Create a new Astra DB Serverless database. While you can easily create one in Astra Portal, another option is to create the database programmatically.

This and the following topics are also presented in the Administration Reference. They are included here for convenience.

  • Python

  • TypeScript

  • Java

  • CLI

View this topic in more detail on the API Reference.

The database creation is done through an instance of the AstraDBAdmin class.

new_db_admin = admin.create_database(
    "new_database",
    cloud_provider="aws",
    region="ap-south-1",
)

Returns:

AstraDBDatabaseAdmin - A Database Admin object representing the newly-created database.

Example response
AstraDBDatabaseAdmin(id="01234567-89ab-cdef-0123-456789abcdef", "AstraCS:aAbB...")

Parameters:

Name Type Summary

name

str

The desired name for the database.

wait_until_active

bool

If True (default), the method returns only after the newly-created database is in ACTIVE state (a few minutes, usually). If False, it will return right after issuing the creation request to the DevOps API, and it will be responsibility of the caller to check the database status before working with it.

cloud_provider

str

one of 'aws', 'gcp' or 'azure'.

region

str

any of the available cloud regions.

namespace

Optional[str]

name for the one namespace the database starts with. If omitted, DevOps API will use its default.

max_time_ms

Optional[int]

A timeout, in milliseconds, for the whole requested operation to complete. Note that a timeout is no guarantee that the creation request has not reached the API server.

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
admin = client.get_admin()
new_db_admin = admin.create_database(
    "new_database",
    cloud_provider="aws",
    region="ap-south-1",
)
new_db = new_db_admin.get_database()
coll = new_db.create_collection("movies", dimension=512)
coll.insert_one({"title": "The Title"}, vector=...)

View this topic in more detail on the API Reference.

The database creation is done through an instance of the AstraAdmin class.

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

Parameters:

Name Type Summary

config

DatabaseConfig

The properties of the database to create.

options?

AdminBlockingOptions

Options regarding the creation of the database.

Config (DatabaseConfig):

Name Type Summary

name

string

Name of the database (non-unique user-friendly identifier)

cloudProvider

DatabaseCloudProvider

Cloud provider where the database lives

region

string

The cloud region where the database is located.

namespace?

string

Overrides the default namespace (keyspace)

Returns:

Promise<AstraDbAdmin> - A promised instance of the AstraDbAdmin class for that database.

Example:

import { DataAPIClient } from '@datastax/astra-db-ts'

// Obtain an admin instance
const admin = new DataAPIClient('TOKEN').admin();

(async function () {
  // Create a new database
  const dbAdmin = await admin.createDatabase({
    name: 'my-database',
    region: 'us-east1',
    cloudProvider: 'GCP',
  });

  // Get and use the database
  const db = dbAdmin.db();
  console.log(await db.listCollections());
})();

The createDatabase method blocks until the database is active, by default. This entails polling the database status until it is ACTIVE. You can disable this behavior by passing { blocking: false } to the options parameter.

Creating a database is available in the AstraDBAdmin class.

// Given 'client' an instance of 'DataAPIClient'
AstraDBAdmin admin = client.getAdmin();
DatabaseAdmin dbAdmin1 = admin.createDatabase(String name);
DatabaseAdmin dbAdmin2 = admin.createDatabase(String name, CloudProviderType cloud, String cloudRegion);
DatabaseAdmin dbAdmin3 = admin.createDatabase(String name, CloudProviderType cloud, String cloudRegion, boolean waitActive);

Parameters:

Name Type Summary

name

String

The name of the database to create.

cloud

CloudProviderType

The cloud provider where the database will be created.

cloudRegion

String

The region of the cloud provider where the database will be created.

waitActive

boolean

Default behavior is synchronous and wait for the database to be active; if the parameter is provided, the operation will be asynchronous.

Returned Values:

Type Description

DatabaseAdmin

The administration object for the database to manage namespaces or to access the database.

You cannot use the database until it is created and its status is ACTIVE.

Example:

package com.datastax.astra.client.admin;

import com.datastax.astra.client.admin.AstraDBAdmin;
import com.datastax.astra.client.DataAPIClient;
import com.dtsx.astra.sdk.db.domain.CloudProviderType;

import java.util.UUID;

public class CreateDatabase {
  public static void main(String[] args) {
    AstraDBAdmin astraDBAdmin = new DataAPIClient("TOKEN").getAdmin();

    // Choose a cloud provider (GCP, AZURE, AWS) and a region
    CloudProviderType cloudProvider = CloudProviderType.GCP;
    String cloudRegion = "us-east1";

    // Create a database
    DatabaseAdmin admin = astraDBAdmin.createDatabase("DATABASE_NAME", cloudProvider, cloudRegion);
  }
}

To create a database, use the following command:

astra db create <db_name> \
   --region <region>
   --cloud <cloud>  \
   -k <keyspace> \
   --if-not-exist
   --async

Arguments:

Options Type Description

db_name

String

The desired name for the database.

region

String (OPTIONAL)

The region where to create the database, it goes with the cloud provider.

cloud

String (OPTIONAL)

The cloud provider (gcp,azure,aws) where to create the database.

keyspace

String (OPTIONAL)

The name of the namespace, if not provided default is default_keyspace.

--if-not-exists

flag (OPTIONAL)

If provided, make the operation idempotent.

--async

flag (OPTIONAL)

Default behavior is synchronous and wait for the db to be active; if this parameters is provided, the operation will be asynchronous.

The command will wait until the database is created and ready to use. To know more use the command astra help db create.

Get database information

Get all information on a database.

  • Python

  • TypeScript

  • Java

  • CLI

View this topic in more detail on the API Reference.

This operation is done through an instance of the AstraDBAdmin class.

db_info = admin.database_info("01234567-...")

Parameters:

Name Type Summary

id

str

The ID of the target database, e. g. "01234567-89ab-cdef-0123-456789abcdef".

max_time_ms

Optional[int]

A timeout, in milliseconds, for the API request.

Returns:

AdminDatabaseInfo - An object containing the requested information.

Example response
# (output below abridged and reformatted in pprint-style for clarity)

AdminDatabaseInfo(
    info=DatabaseInfo(
        id='01234567-89ab-cdef-0123-456789abcdef',
        region='us-east1',
        namespace='default_keyspace',
        name='my_database',
        environment='prod',
        raw_info={
            'additionalKeyspaces': [
                'default_keyspace',
                'my_dreamspace'
            ],
            'capacityUnits': 1,
            'cloudProvider': 'GCP',
            'datacenters': [
                {
                    'capacityUnits': 1,
                    'cloudProvider': 'GCP',
                    'dateCreated': '2023-06-05T21:29:46Z',
                    'id': '01234567-89ab-cdef-0123-456789abcdef-1',
                    'isPrimary': True,
                    'name': 'dc-1',
                    'region': 'us-east1',
                    'regionClassification': 'standard',
                    'regionZone': 'na',
                    'secureBundleInternalUrl': 'https://...',
                    'secureBundleMigrationProxyInternalUrl': 'https://...',
                    'secureBundleMigrationProxyUrl': 'https://...',
                    'secureBundleUrl': 'https://datastax-cluster...',
                    'status': '',
                    'tier': 'serverless'
                }
            ],
            'dbType': 'vector',
            'keyspace': 'default_keyspace',
            'keyspaces': [
                'default_keyspace',
                'my_dreamspace'
            ],
            'name': 'my_database',
            'region': 'us-east1',
            'tier': 'serverless'
        }
    ),
    available_actions=[
        'getCreds',
        'addDatacenters',
        '...',
        'hibernate'
    ],
    cost={
        'costPerDayCents': 0,
        'costPerDayMRCents': 0,
        '...': 0,
        'costPerReadGbCents': 0.1,
        'costPerWrittenGbCents': 0.1
    },
    cqlsh_url='https://01234567-....datastax.com/cqlsh',
    creation_time='2023-06-05T21:29:46Z',
    data_endpoint_url='https://01234567-....datastax.com/api/rest',
    grafana_url='https://01234567-....datastax.com/d/cloud/...',
    graphql_url='https://01234567-....datastax.com/api/graphql',
    id='01234567-89ab-cdef-0123-456789abcdef',
    last_usage_time='2024-03-22T15:00:14Z',
    metrics={
        'errorsTotalCount': 0,
        'liveDataSizeBytes': 0,
        'readRequestsTotalCount': 0,
        'writeRequestsTotalCount': 0
    },
    observed_status='ACTIVE',
    org_id='aabbccdd-eeff-0011-2233-445566778899',
    owner_id='00112233-4455-6677-8899aabbddeeff',
    status='ACTIVE',
    storage={
        'displayStorage': 10,
        'nodeCount': 3,
        'replicationFactor': 1,
        'totalStorage': 5
    },
    termination_time='0001-01-01T00:00:00Z',
    raw_info={...}
)

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
admin = client.get_admin()

db_details = admin.database_info("01234567-...")
db_details.id
# '01234567-...'
db_details.status
# 'ACTIVE'
db_details.info.region
# 'eu-west-1'

The TypeScript client does not support this operation.

// Given 'admin' an instance of 'AstraDBAdmin'
DatabaseInfo info = admin.getDatabaseInfo(UUID id);

Parameters:

Name Type Summary

id

UUID

The unique identifier of the database to find.

name

String

The name of the database to find.

Returned values:

Type Description

DatabaseInfo

Database information wrapped as an object. The UUID ensures that the database is unique; you get one database or nothing.

Example:

package com.datastax.astra.client.admin;

import com.datastax.astra.client.admin.AstraDBAdmin;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.DatabaseInfo;

import java.util.UUID;

public class GetDatabaseInformation {
  public static void main(String[] args) {

    AstraDBAdmin astraDBAdmin = new DataAPIClient("TOKEN").getAdmin();

    // Check if a database exists
    boolean exists1 = astraDBAdmin.databaseExists("database_name");
    boolean exists2 = astraDBAdmin.databaseExists(UUID.fromString("<database_id>"));

    // Find a database by name (names may not be unique)
    DatabaseInfo databaseInformation = astraDBAdmin
            .getDatabaseInfo(UUID.fromString("<database_id>"));
    System.out.println("Name=" + databaseInformation.getName());
  }
}

To access details about a database, use the following commands:

astra db describe <database_name>
astra db describe <database_id>

Find all databases

Retrieve the listing of all databases.

  • Python

  • TypeScript

  • Java

  • CLI

View this topic in more detail on the API Reference.

This operation is done through an instance of the AstraDBAdmin class.

all_databases = admin.list_databases()

Parameters:

Name Type Summary

max_time_ms

Optional[int]

A timeout, in milliseconds, for the API request.

Returns:

CommandCursor[AdminDatabaseInfo] - An iterable of AdminDatabaseInfo objects, each carrying detailed information on a database.

Example response
# (output below abridged and reformatted in pprint-style for clarity)
# (a single example AdminDatabaseInfo from the cursor is shown)

[
    ...,
    AdminDatabaseInfo(
        info=DatabaseInfo(
            id='01234567-89ab-cdef-0123-456789abcdef',
            region='us-east1',
            namespace='default_keyspace',
            name='my_database',
            environment='prod',
            raw_info={
                'additionalKeyspaces': [
                    'default_keyspace',
                    'my_dreamspace'
                ],
                'capacityUnits': 1,
                'cloudProvider': 'GCP',
                'datacenters': [
                    {
                        'capacityUnits': 1,
                        'cloudProvider': 'GCP',
                        'dateCreated': '2023-06-05T21:29:46Z',
                        'id': '01234567-89ab-cdef-0123-456789abcdef-1',
                        'isPrimary': True,
                        'name': 'dc-1',
                        'region': 'us-east1',
                        'regionClassification': 'standard',
                        'regionZone': 'na',
                        'secureBundleInternalUrl': 'https://...',
                        'secureBundleMigrationProxyInternalUrl': 'https://...',
                        'secureBundleMigrationProxyUrl': 'https://...',
                        'secureBundleUrl': 'https://datastax-cluster...',
                        'status': '',
                        'tier': 'serverless'
                    }
                ],
                'dbType': 'vector',
                'keyspace': 'default_keyspace',
                'keyspaces': [
                    'default_keyspace',
                    'my_dreamspace'
                ],
                'name': 'my_database',
                'region': 'us-east1',
                'tier': 'serverless'
            }
        ),
        available_actions=[
            'getCreds',
            'addDatacenters',
            '...',
            'hibernate'
        ],
        cost={
            'costPerDayCents': 0,
            'costPerDayMRCents': 0,
            '...': 0,
            'costPerReadGbCents': 0.1,
            'costPerWrittenGbCents': 0.1
        },
        cqlsh_url='https://01234567-....datastax.com/cqlsh',
        creation_time='2023-06-05T21:29:46Z',
        data_endpoint_url='https://01234567-....datastax.com/api/rest',
        grafana_url='https://01234567-....datastax.com/d/cloud/...',
        graphql_url='https://01234567-....datastax.com/api/graphql',
        id='01234567-89ab-cdef-0123-456789abcdef',
        last_usage_time='2024-03-22T15:00:14Z',
        metrics={
            'errorsTotalCount': 0,
            'liveDataSizeBytes': 0,
            'readRequestsTotalCount': 0,
            'writeRequestsTotalCount': 0
        },
        observed_status='ACTIVE',
        org_id='aabbccdd-eeff-0011-2233-445566778899',
        owner_id='00112233-4455-6677-8899aabbddeeff',
        status='ACTIVE',
        storage={
            'displayStorage': 10,
            'nodeCount': 3,
            'replicationFactor': 1,
            'totalStorage': 5
        },
        termination_time='0001-01-01T00:00:00Z',
        raw_info={...}
    ),
    ...
]

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
admin = client.get_admin()

database_cursor = admin.list_databases()
database_list = list(database_cursor)
len(database_list)
# 3
database_list[2].id
# '01234567-...'
database_list[2].status
# 'ACTIVE'
database_list[2].info.region
# 'eu-west-1'

View this topic in more detail on the API Reference.

This operation is done through an instance of the AstraAdmin class.

const dbs = await admin.listDatabases();

Parameters:

Name Type Summary

options

ListDatabasesOptions

The filters to use when listing the database

Name Type Summary

include?

DatabaseStatus

Allows filtering by database status. Defaults to NONTERMINATED.

provider?

DatabaseCloudProviderFilter

Allows filtering by cloud provider. Defaults to ALL.

limit?

number

Number of databases to return, between 1-100. Defaults to 25.

skip?

number

Number of databases to skip. Defaults to 0.

maxTimeMs?

number

Maximum time in milliseconds the client should wait for the operation to complete.

Returns:

Promise<FullDatabaseInfo[]> - A promised list of the complete information for all the databases matching the given filter.

Example:

import { DataAPIClient } from '@datastax/astra-db-ts'

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

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

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

Listing databased function is available in the AstraDBAdmin class

// Given 'admin' an instance of 'AstraDBAdmin'
String<String> nameList = admin.listDatabaseNames();
String<DatabaseInfo> infoList = admin.listDatabases();

Returned Values:

Type Description

List<DatabaseInfo>

Database information list exposed as a Stream.

Example:

package com.datastax.astra.client.admin;

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.DatabaseInfo;

public class ListDatabases {
    public static void main(String[] args) {
        
        // Initialization of admin (astra only)
        AstraDBAdmin astraDBAdmin = new DataAPIClient("TOKEN").getAdmin();

        // Display all database information
        astraDBAdmin.listDatabases().stream()
                .map(DatabaseInfo::getId)
                .forEach(System.out::println);

        // Display all database names
        astraDBAdmin.listDatabaseNames();
    }
}

To list all databases, use the following command:

astra db list
Example response
+---------------------+--------------------------------------+-----------+-------+---+-----------+
| Name                | id                                   | Regions   | Cloud | V | Status    |
+---------------------+--------------------------------------+-----------+-------+---+-----------+
| astra_db_client     | 4391daae-016c-49e3-8d0a-b4633a86082c | us-east1  | gcp   | ■ | ACTIVE    |
+---------------------+--------------------------------------+-----------+-------+---+-----------+

Drop a database

Drop (delete) a database, erasing all data stored in it as well.

  • Python

  • TypeScript

  • Java

  • CLI

View this topic in more detail on the API Reference.

The database deletion is done through an instance of the AstraDBAdmin class.

admin.drop_database("01234567-...")

Parameters:

Name Type Summary

id

str

The ID of the database to drop, e. g. "01234567-89ab-cdef-0123-456789abcdef".

wait_until_active

bool

If True (default), the method returns only after the database has actually been deleted (generally a few minutes). If False, it will return right after issuing the drop request to the DevOps API, and it will be responsibility of the caller to check the database status/availability after that, if desired.

max_time_ms

Optional[int]

A timeout, in milliseconds, for the whole requested operation to complete. Note that a timeout is no guarantee that the deletion request has not reached the API server.

Returns:

Dict - A dictionary in the form {"ok": 1} if the method succeeds.

Example response
{"ok": 1}

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
admin = client.get_admin()

database_list_pre = list(admin.list_databases())
len(database_list_pre)
# 3
admin.drop_database("01234567-...")
# {'ok': 1}
database_list_post = list(admin.list_databases())
len(database_list_post)
# 2

View this topic in more detail on the API Reference.

The database termination is done through an instance of the AstraAdmin class.

await admin.dropDatabase('DB_ID');

Parameters:

Name Type Summary

db

Db | string

The Db, or database ID, to drop.

options?

AdminBlockingOptions

Options regarding the termination of the database.

Returns:

Promise<void> - A promise that resolves when the database is terminated.

Example:

import { DataAPIClient } from '@datastax/astra-db-ts'

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

(async function () {
  await admin.dropDatabase('DB_ID');
})();

The dropDatabase method blocks until the database is deleted, by default. This entails polling the database status until it is TERMINATED. You can disable this behavior by passing { blocking: false } to the options parameter.

Listing databased function is available in the AstraDBAdmin class.

boolean AstraDBAdmin.deleteDatabase(String name);
boolean AstraDBAdmin.deleteDatabase(UUID id);

Parameters:

Name Type Summary

id

UUID

The identifier of the database to delete.

name

String

The name of the database to delete.

Returned Values:

Type Description

boolean

Flag indicating if the database was deleted.

Example:

package com.datastax.astra.client.admin;

import com.datastax.astra.client.admin.AstraDBAdmin;
import com.datastax.astra.client.DataAPIClient;

import java.util.UUID;

public class DropDatabase {
  public static void main(String[] args) {
    AstraDBAdmin astraDBAdmin = new DataAPIClient("TOKEN").getAdmin();

    // Delete an existing database
    astraDBAdmin.dropDatabase("<database_name>");

    // Delete an existing database by ID
    astraDBAdmin.dropDatabase(UUID.fromString("<database_id>"));

  }
}

To delete a database, use the following command:

astra db delete <db_name>
astra db delete <db_id>

Parameters:

Name Type Summary

db_id

UUID

The identifier of the database to delete.

db_name

String

The name of the database to delete.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com