Administration reference

In order to perform administrative operations, specific classes are used: one to work at the level of databases (e.g. to create a new database), and one to work within a specific database (e.g. to create a new namespace).

The former class ("Astra DB Admin" in the following — the exact class name depends on the language being used) is obtained from the client, while the latter ("Database Admin") is created, in turn, by the Astra DB Admin.

Get an Astra DB Admin

The client can generate an AstraDBAdmin object.

  • Python

  • TypeScript

  • Java

View this topic in more detail on the API Reference.

admin = client.get_admin()

Parameters:

Name Type Summary

token

Optional[str]

If supplied, is passed to the Astra DB Admin instead of the client token. This may be useful when switching to a more powerful, admin-capable permission set.

Returns:

AstraDBAdmin - An object used for database-level administrative tasks.

Example response
AstraDBAdmin("AstraCS:aAbB...")

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
admin = client.get_admin()
databases = admin.list_databases()
new_db_admin = admin.create_database(
    "the_other_database",
    cloud_provider="AWS",
    region="eu-west-1",
)
new_db_admin.list_namespaces()
# ['default_keyspace', 'that_other_one']

View this topic in more detail on the API Reference.

const admin = client.admin();

Parameters:

Name Type Summary

options?

AdminSpawnOptions

The options to use for the admin

Options (AdminSpawnOptions):

Name Type Summary

adminToken?

string

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

monitorCommands?

boolean

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

endpointUrl?

string

Base URL for the DevOps API

Returns:

AstraAdmin - An object used for database-management-level administrative tasks.

Example:

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

const client = new DataAPIClient('TOKEN');

// Spawn an AstraAdmin instance
const admin = client.admin();

(async function () {
  // List all non-terminated databases
  console.log(await admin.listDatabases());

  // Create an actual new database
  const newDbAdmin = await admin.createDatabase({
    name: 'the_other_database',
    cloudProvider: 'aws',
    region: 'eu-west-1',
  });

  // Prints ['default_keyspace']
  console.log(await newDbAdmin.listNamespaces());
});
// Given 'client' an instance of 'DataAPIClient'
AstraDBAdmin admin = client.getAdmin();
AstraDBAdmin admin = client.getAdmin("token");

Returns: AstraDBAdmin - An object used for database-level administrative tasks (astra-only) Parameters:

Name Type Summary

token

String

If supplied, is passed to the Astra DB Admin instead of the client token. This may be useful when switching to a more powerful, admin-capable permission set.

Example:

package com.datastax.astra.client;


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

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

public class ConnectingAdmin {
    public static void main(String[] args) {
        // Default Initialization
        DataAPIClient client = new DataAPIClient("TOKEN");

        // Accessing admin providing a new token possibly with stronger permissions
        AstraDBAdmin astradbAdmin = client.getAdmin("SUPER_USER_TOKEN");

        // Create a Database
        astradbAdmin.createDatabase("db-demo", GCP, "us-east-1").listNamespaceNames();
    }
}

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.

  • Python

  • TypeScript

  • Java

  • CLI

View this topic in more detail on the API Reference.

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.

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.

// Given 'admin' a AstraDBAdmin object
DatabaseAdmin new_db_admin1 = admin.createDatabase(String name);
DatabaseAdmin new_db_admin2 = admin.createDatabase(
        String name,
        CloudProviderType cloudProvider,
        String cloudRegion);
DatabaseAdmin new_db_admin = admin.createDatabase(
        String name,
        CloudProviderType cloudProvider,
        String cloudRegion,
        boolean waitUntilActive)

Returns:

DatabaseAdmin - An instance of Database administration object.

Parameters:

Name Type Summary

name

String

The desired name for the database.

cloudProvider

CloudProviderType

One of 'aws', 'gcp' (default) or 'azure'.

region

String

Any of the available cloud regions (default: 'us-east1').

waitUntilActive

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.

Example:

package com.datastax.astra.client.admin;

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

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

Parameters

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

Find all databases

Retrieve the listing of all databases.

  • Python

  • TypeScript

  • Java

  • CLI

View this topic in more detail on the API Reference.

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.

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

The maximum time in milliseconds that 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`);
  }
})();
// Given 'admin' a AstraDBAdmin object
List<DatabaseInfo> infoList = admin.listDatabases();

Returns:

list of DatabaseInfo - Detailing metadata about the databases.

Parameters:

None.

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.

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.

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.

// Given 'admin', a AstraDBAdmin object

// Delete an existing database from its name
admin.dropDatabase(String name);

// Delete an existing database from its ID
admin.dropDatabase(UUID id);

Returns: DatabaseAdmin - An instance of Database administration object. Parameters

Name Type Summary

name

String

The desired name for the database.

id

UUID

The desired identifier for the database.

Example:

package com.datastax.astra.client.admin;

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.

Get database information

Get all information on a database.

  • Python

  • TypeScript

  • Java

  • CLI

View this topic in more detail on the API Reference.

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'

View this topic in more detail on the API Reference.

const dbInfo = admin.dbAdmin('DB_ID');

Parameters:

Name Type Summary

id

string

The ID of the target database.

options?

WithTimeout

The options (the timeout) for this operation.

Returns:

Promise<FullDatabaseInfo> - A promise that resolves to the complete information for the corresponding database.

Example:

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

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

(async function () {
  const details = await admin.dbInfo('DB_ID');
  console.log(details.id); // '01234567-...'
  console.log(details.status); // 'ACTIVE'
  console.log(details.info.region); // 'eu-west-1'
})();
// Given 'admin', a AstraDBAdmin object

// Delete an existing database from its name
admin.getDatabaseInfo(UUID databaseId);

Returns: DatabaseInfo - Object detailing metadata about the database. Parameters

Name Type Summary

databaseId

UUID

The desired identifier for the database.

Example:

package com.datastax.astra.client.admin;

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());
  }
}

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                            |
|                  |                                         |
+------------------+-----------------------------------------+

Get a Database Admin

The Database Admin object can perform administrative tasks within a database, such as managing namespaces. An Astra DB Admin can instantiate one such object for any existing database.

  • Python

  • TypeScript

  • Java

  • CLI

View this topic in more detail on the API Reference.

db_admin = admin.get_database_admin("01234567-...")

Parameters:

Name Type Summary

id

UUID

The ID of the target database. For example "01234567-89ab-cdef-0123-456789abcdef".

Returns:

AstraDBDatabaseAdmin - A Database Admin object representing the target database.

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

Example:

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

db_admin = admin.get_database_admin("01234567-...")
db_admin.list_namespaces()
# ['default_keyspace']
db_admin.create_namespace("that_other_one")
# {'ok': 1}
db_admin.list_namespaces()
# ['default_keyspace', 'that_other_one']

View this topic in more detail on the API Reference.

const dbAdmin = admin.dbAdmin('ENDPOINT');

Or use the convince method to get by ID and region:

const dbAdmin = admin.dbAdmin('DB_ID', 'REGION');

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

dbOptions?

DbSpawnOptions

The options to use for the underlying database (see Connect to a Database for more information). The admin options are taken from the parrent admin instance.

Returns:

AstraDbAdmin - An object used for database-specific-level administrative tasks.

Example:

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

// Spawn an AstraDbAdmin instance
const admin = new DataAPIClient('TOKEN').admin();
const dbAdmin = admin.dbAdmin('ENDPOINT');

(async function () {
  // ['default_keyspace']
  console.log(await dbAdmin.listNamespaces());

  await dbAdmin.createNamespace('that_other_one');

  // ['default_keyspace', 'that_other_one']
  console.log(await dbAdmin.listNamespaces());
})();
// Given 'admin', a AstraDBAdmin object
DatabaseAdmin dbAdmin = admin
  .getDatabaseAdmin(UUID.fromString("<database_id>"));

Returns:

DatabaseAdmin - An instance of Database administration object.

Parameters

Name Type Summary

id

UUID

The desired identifier for the database.

Example:

package com.datastax.astra.client.database_admin;


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

import java.util.UUID;

public class GetDatabaseAdmin {
    public static void main(String[] args) {
        // Default Initialization
        DataAPIClient client = new DataAPIClient("TOKEN");

        // Accessing admin providing a new token possibly with stronger permissions
        AstraDBAdmin astradbAdmin = client.getAdmin("SUPER_USER_TOKEN");

        DatabaseAdmin admin = astradbAdmin.getDatabaseAdmin(UUID.fromString("<database_id>"));
    }
}
Hello Astra CLI world. TBD.

Create a namespace

Databases come equipped with one default_namespace already. However, it may be convenient to create more as a way to better structure applications.

  • Python

  • TypeScript

  • Java

  • CLI

View this topic in more detail on the API Reference.

db_admin.create_namespace("that_other_one")

Parameters:

Name Type Summary

name

str

The namespace name. If supplying a namespace that exists already, the method call proceeds as usual, no errors are raised, and the whole invocation is a no-op.

wait_until_active

Type

If True (default), the method returns only after the target database is in ACTIVE state again (a few seconds, 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/namespace availability before working with it.

max_time_ms

Type

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.

Returns:

Dict - A dictionary of the form {"ok": 1} if the operation succeeds. Otherwise, an exception is raised.

Example response
{"ok": 1}

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
db_admin = client.get_admin().get_database_admin("01234567-...")

db_admin.list_namespaces()
# ['default_keyspace']
db_admin.create_namespace("that_other_one")
# {'ok': 1}
db_admin.list_namespaces()
# ['default_keyspace', 'that_other_one']

View this topic in more detail on the API Reference.

await admin.createNamespace('that_other_one');

Parameters:

Name Type Summary

name

string

The name of the namespace to create.

options?

AdminBlockingOptions

Blocking options regarding the creation of the namespace.

Returns:

Promise<void> - A promise that resolves when the namespace is created (or when the initial request completes if not blocking).

Example:

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

// Spawn an AstraDbAdmin instance
const admin = new DataAPIClient('TOKEN').admin();
const dbAdmin = admin.dbAdmin('ENDPOINT');

(async function () {
  // ['default_keyspace']
  console.log(await dbAdmin.listNamespaces());

  await dbAdmin.createNamespace('that_other_one');

  // ['default_keyspace', 'that_other_one']
  console.log(await dbAdmin.listNamespaces());
});

The createNamespace 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.

// Given 'dbAdmin', a DatabaseAdmin object
void dbAdmin.createNamespace("namespace");

Returns:

None.

Parameters:

Name Type Summary

namespace

String

The unique name for the namespace

Example:

package com.datastax.astra.client.database_admin;

import com.datastax.astra.client.Database;

public class CreateNamespace {
  public static void main(String[] args) {
    // Default initialization
    Database db = new Database("API_ENDPOINT", "TOKEN");

    // Create a new namespace
    db.getDatabaseAdmin().createNamespace("<namespace_name>");
  }
}

To create a namespace, use the following command:

astra db create-keyspace <db_name> -k <namespace_name>

Parameters:

Name Type Summary

db_name

String

The name of the database where the namespace will be created. (must exists)

namespace_name

String

The unique name for the namespace

List namespaces

Get a list of the namespaces found in a database.

  • Python

  • TypeScript

  • Java

  • CLI

View this topic in more detail on the API Reference.

namespaces = db_admin.list_namespaces()

Parameters:

Name Type Summary

max_time_ms

Optional[int]

A timeout, in milliseconds, for the API request.

Returns:

List[str] - A list of the namespaces with their names appearing in no particular order.

Example response
['default_keyspace', 'that_other_one']

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
db_admin = client.get_admin().get_database_admin("01234567-...")

db_admin.list_namespaces()
# ['default_keyspace']
db_admin.create_namespace("that_other_one")
# {'ok': 1}
db_admin.list_namespaces()
# ['default_keyspace', 'that_other_one']

View this topic in more detail on the API Reference.

const namespaces = await admin.listNamespaces();

Parameters:

Name Type Summary

options?

WithTimeout

Options regarding the timeout for the operation.

Returns:

Promise<string[]> - A list of the namespaces, with the first namespace being the default one.

Example:

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

// Spawn an AstraDbAdmin instance
const admin = new DataAPIClient('TOKEN').admin();
const dbAdmin = admin.dbAdmin('ENDPOINT');

(async function () {
  // ['default_keyspace']
  console.log(await dbAdmin.listNamespaces());

  await dbAdmin.createNamespace('that_other_one');

  // ['default_keyspace', 'that_other_one']
  console.log(await dbAdmin.listNamespaces());
});
// Given 'dbAdmin', a DatabaseAdmin object
Set<String> names = dbAdmin.listNamespaceNames();

Parameters:

None.

Returns:

Name Type Summary

namespace

Set<String>

The list of available namespaces in current database.

Example:

package com.datastax.astra.client.database_admin;

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

import java.util.Set;
import java.util.UUID;

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

        DataAPIClient client = new DataAPIClient("TOKEN");

        // Accessing admin providing a new token possibly with stronger permissions
        AstraDBAdmin admin = client.getAdmin("SUPER_USER_TOKEN");

        DatabaseAdmin dbAdmin = admin.getDatabaseAdmin(UUID.fromString("DATABASE_ID"));

        // List available namespaces
        Set<String> names = dbAdmin.listNamespaceNames();
    }
}

To list the namespaces in a database, use the following command:

astra db list-keyspaces <db_name>

Parameters:

Name Type Summary

db_name

String

The name of the database where the namespace will be created. (must exists)

Sample output:

+----------------------------+
| Name                       |
+----------------------------+
| default_keyspace (default) |
| namespace2                 |
+----------------------------+

Drop a namespace

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

  • Python

  • TypeScript

  • Java

  • CLI

View this topic in more detail on the API Reference.

db_admin.drop_namespace("legacy_namespace")

Parameters:

Name Type Summary

name

str

The namespace to delete. If it does not exist in this database, an error is raised.

wait_until_active

bool

If True (default), the method returns only after the target database is in ACTIVE state again (a few seconds, usually). If False, it will return right after issuing the deletion request to the DevOps API, and it will be responsibility of the caller to check the database status/namespace availability before working with it.

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 of the form {"ok": 1} if the operation succeeds. Otherwise, an exception is raised.

Example response
{"ok": 1}

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
db_admin = client.get_admin().get_database_admin("01234567-...")

db_admin.list_namespaces()
# ['default_keyspace', 'that_other_one']
db_admin.drop_namespace("that_other_one")
# {'ok': 1}
db_admin.list_namespaces()
# ['default_keyspace']

View this topic in more detail on the API Reference.

await admin.dropNamespace('legacy_namespace');

Parameters:

Name Type Summary

name

string

The name of the namespace to drop.

options?

AdminBlockingOptions

Blocking options regarding the deletion of the namespace.

Returns:

Promise<void> - A promise that resolves when the namespace is deleted (or when the initial request completes if not blocking).

Example:

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

// Spawn an AstraDbAdmin instance
const admin = new DataAPIClient('TOKEN').admin();
const dbAdmin = admin.dbAdmin('ENDPOINT');

(async function () {
  // ['default_keyspace', 'that_other_one']
  console.log(await dbAdmin.listNamespaces());

  await dbAdmin.dropNamespace('that_other_one');

  // ['default_keyspace']
  console.log(await dbAdmin.listNamespaces());
});

The dropNamespace 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.

// Given 'dbAdmin', a DatabaseAdmin object
void dbAdmin.dropNamespace("namespace");

Parameters:

Name Type Summary

namespace

String

The name of the namespace to delete.

Example:

package com.datastax.astra.client.database_admin;

import com.datastax.astra.client.Database;

public class DropNamespace {

    public static void main(String[] args) {
        // Default initialization
        Database db = new Database("API_ENDPOINT", "TOKEN");

        // Drop a Namespace
        db.getDatabaseAdmin().dropNamespace("<namespace_name>");
    }
}

To delete a namespace, use the following command:

astra db delete-keyspace <db_name> -k <namespace_name>

Parameters:

Name Type Summary

db_name

String

The name of the database where the namespace will be deleted. (must exists)

namespace_name

String

The unique name for the namespace

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