Create an Astra Managed Clusters database

Astra Managed Clusters databases are built on Apache Cassandra®, an open-source NoSQL distributed database, making them highly scalable and reliable.

Astra Managed Clusters databases start with the following specifications:

A single region
A single keyspace
Storage based on the workload capacity tier
Capacity for up to 200 tables
Triple replication for optimal uptime and data integrity

Prerequisites

If you plan to bring your own encryption keys, you must create and register your customer keys before creating databases.

You need a role with the Create DB permission, such as the Organization Administrator or Database Administrator role. To create databases programmatically, you need an application token with an appropriately scoped role.

Create an Astra Managed Clusters database in the Astra Portal

In the Astra Portal, click Create database.
Click Managed clusters.
Enter a meaningful, human-readable database name.

You cannot change the database name after you create the database.

Database names must follow these rules:
- Must start and end with a letter or number
- Can contain letters, numbers, and the special characters & + - _ ( ) < > . , @
- Cannot exceed 50 characters
Enter a name for the database’s first keyspace.

Keyspace names must follow these rules:
- Must start with a letter or number
- Can contain letters, numbers, and underscores
- Cannot exceed 48 characters.
- Cannot be the reserved words dse or system
- Must be unique within the database
Select a cloud provider and region to host your database.

To minimize latency in production databases, select a region that is close to your application’s users.

For multi-region availability, you can add more regions after you create the database.
Select a Workload Type and Workload Size for this database. For more information, see workload capacity tiers.
Click Create database.

Wait for your database to initialize and reach Active status. This can take several minutes.

Once your database is active, you can create keyspaces and tables, load data, and connect to your database.

Create an Astra Managed Clusters database with the DevOps API

You can use the DevOps API to create databases programmatically:

curl -sS -L -X POST "https://api.astra.datastax.com/v2/databases" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "name": "DATABASE_NAME",
  "keyspace": "KEYSPACE_NAME",
  "cloudProvider": "CLOUD_PROVIDER",
  "region": "REGION"
  "tier": "WORKLOAD_PLAN",
  "capacityUnits": CAPACITY_UNITS
}'

Replace the following:

APPLICATION_TOKEN: An application token with a role that has permission to create databases.
DATABASE_NAME: A meaningful, human-readable database name.

You cannot change the database name after you create the database.

Database names must follow these rules:

Must start and end with a letter or number
Can contain letters, numbers, and the special characters & + - _ ( ) < > . , @
Cannot exceed 50 characters

KEYSPACE_NAME: A name for the database’s first keyspace.

Keyspace names must follow these rules:
- Must start with a letter or number
- Can contain letters, numbers, and underscores
- Cannot exceed 48 characters.
- Cannot be the reserved words dse or system
- Must be unique within the database
CLOUD_PROVIDER: One of 'aws', 'gcp', or 'azure'.

REGION: A valid cloud provider region, depending on the subscription plan and workload tier.

To minimize latency in production databases, select a region that is close to your application’s users.

For multi-region availability, you can add more regions after you create the database.

You can use the DevOps API to Get supported regions, tiers, and capacity.

curl -sS -L -X GET "https://api.astra.datastax.com/v2/availableRegions" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Accept: application/json"

WORKLOAD_PLAN: Provide a valid workload capacity tier for the database. One of C20, C40, D10, D20, or D40.

For C40i and E tier plans, you must create the database in the Astra Portal.
CAPACITY_UNITS: The initial number of capacity units for the database. This is the amount of space available (horizontal scaling) for the database. For C and D tier, the max is 12 on startup.

A successful request returns 201 Created and the database ID. However, it takes several minutes for the database to initialize and reach Active status.

Once your database is active, you can create keyspaces and tables, load data and connect to your database.

Get database details

After you create an Astra Managed Clusters database, you can get information about it, such as the database name, ID, status, and regions.

At minimum, you can access databases that you create. Your role determines whether you have access to databases created by other users in your Astra organization.

Get database details in the Astra Portal

In the Astra Portal, click Managed clusters to view a summary of your organization’s Astra Managed Clusters databases. To inspect a specific database, click the database’s name on the Managed clusters dashboard.

Get details for one database with the DevOps API

To get information about a specific database, use GET /v2/databases/DATABASE_ID:

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases/DATABASE_ID" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

Replace the following:

DATABASE_ID: The database ID.
APPLICATION_TOKEN: An application token with a role that is permitted to view the specified database, such as the Database Administrator role.

A successful request returns 200 Created and an object containing database information.

Get details for all databases in an organization with the DevOps API

To get all databases in an organization, use GET /v2/databases:

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

The organization to query is inferred from the application token.

The application token must have a role that is permitted to view all databases in the organization, such as the Organization Administrator role.

A successful request returns 200 Created and an array of objects containing information about each database in the organization.

Get database details with the Astra CLI

The Astra CLI provides several commands to get information about databases, including astra db get and more specific commands like astra db list-regions.

Get your database ID

Get a database ID in the Astra Portal

In the Astra Portal, click Managed clusters to see a list of all of your databases along with their IDs.

Alternatively, click the name of a specific database to get the database ID from the database details page or in the page URL, such as astra.datastax.com/org/ORGANIZATION_ID/database/DATABASE_ID/.

Get a database ID with the DevOps API

You can use the DevOps API List databases endpoint to get all database IDs at once:

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

Make sure the application token has View DB permission for all relevant databases. For example, the Organization Administrator role can view all databases within an Astra organization. If the supplied token doesn’t have permission to view a particular database, the response won’t include any information for that database.

A successful response contains an array of database objects. In each object, the id field contains the database ID. The following example is truncated for clarity.

Result

[
  {
    "id": "FIRST_DATABASE_ID",
    "orgId": "organizations/ORGANIZATION_ID",
    "ownerId": "users/ADMIN_USER_ID",
    "info": { ... },
    "creationTime": "2012-11-01T22:08:41+00:00",
    "terminationTime": "2019-11-01T22:08:41+00:00",
    "status": "ACTIVE",
    "storage": { ... },
    "availableActions": [ ... ],
    ...
  },
  {
    "id": "SECOND_DATABASE_ID",
    "orgId": "organizations/ORGANIZATION_ID",
    "ownerId": "users/ADMIN_USER_ID",
    "info": { ... },
    "creationTime": "2012-11-01T22:08:41+00:00",
    "terminationTime": "2019-11-01T22:08:41+00:00",
    "status": "ACTIVE",
    "storage": { ... },
    "availableActions": [ ... ],
    ...
  }
]

Get a database ID with the Astra CLI

See astra db get.

Get a database region ID (datacenter ID)

Datacenter IDs are region-specific database IDs for multi-region databases.

Get datacenter IDs in the Astra Portal

In the Astra Portal, click Managed clusters, and then click the name of the database that you want to inspect.
On the Overview tab, in the Regions section, you can find the regions where the database is deployed along with each region’s Datacenter ID.

For single-region databases, there is only one Datacenter ID, which is the database ID suffixed by -1. Multi-region databases have a Datacenter ID for each region.

Get datacenter IDs with the DevOps API

You can use the DevOps API to list all regions for a specific database:

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases/DATABASE_ID/datacenters" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

The response includes information about the database, including datacenter ID (id), region, database type, status, and various access URLs. For multi-region databases, the response includes an object for each region where the database is deployed.

The datacenter ID (id) is the database ID with a numerical suffix. The -1 suffix indicates the primary region, and secondary regions are numbered in the order they were added to the database.

Result

[
  {
    "id": "1234-5678-91011121-3141-1",
    "name": "dc-1234-5678-91011121-3141",
    "tier": "C20",
    "status": "ACTIVE",
    "cloudProvider": "GCP",
    "region": "us-east1",
    "regionZone": "na",
    "regionClassification": "standard",
    "capacityUnits": 2,
    "grafanaUrl": "http://path-to-grafana:port",
    "cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
    "dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
    "secureBundleUrl": "http://s3-signed-bundle-url",
    "secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
    "secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
    "secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
  }
]

Get datacenter IDs with the Astra CLI

See astra db get or astra db list-regions.