Managing your Astra DB database

As a database administrator, you can manage your database. This includes the following tasks:

Create your database

Complete the following steps to create and launch your DataStax Astra DB database.

Procedure

In the Astra Portal, select Create Database. The Serverless (Vector) deployment type, which creates a database that optimizes your AI application, is selected by default. Select Serverless (Non-Vector) to create a standard database without vector capabilities.

Enter a Database Name that is meaningful. You cannot alter the database name after the database is created. Use only alphanumeric characters; there is no character limit.
Enter a Keyspace Name to reflect your data model. You cannot name your keyspace “dse” or “system”. Use only alphanumeric characters and no more than 48 total characters.

From the Region option, select your cloud provider and the region where you want to launch your database. The available regions vary depending on the cloud provider you selected.

Regions with the lock symbol require payment. When selecting a region with a lock, you have the option to upgrade to a pay-as-you-go-plan. If you select a region without a lock, you are still on the free plan.

Select Create Database. An alert appears at the top of the screen when your database is created.
1. If you’ve created a new vector database, select the Overview tab to review the database details, key metrics, collections and more.
2. Click Load Data to begin loading your data to the database.
3. Click Generate Token to download tokens generated for you.

Results

You are redirected to your Organization Dashboard. The new database and status is shown under Databases. You will receive an email when your database creation is complete. Select the database name to manage or connect with your new database.

View your databases

View all databases in your organization, and select a database to view detailed information about the database.

The Dashboard shows all of your databases within your organization, including databases you created and databases created by other team members. From here, you can select an individual database name to manage and connect those databases.

Selecting a database in DataStax Astra DB provides access to detailed information about the database. You can view the keyspaces, size and location of the database, and the estimate cost per hour.

Open a browser, navigate to Astra DB, and log in.
Select a database from the Databases option in the left navigation or from Recent Resources on the home page.
Click the Overview tab.

You can only view connection details and database management operations for databases that you created.
You can see several database details from this tab:
- Database Name
- Status
- Usage for current billing period
  - Read Requests
  - Write Requests
  - Storage Consumed
  - Data Transfer
- Compute Size [Only for Classic tier databases]
- Replication Factor [Only for Classic tier databases]
- Current Capacity [Only for Classic tier databases]
- Regions
  - Provider
  - Area
  - Region
  - Datacenter ID
  - Region Availability
- Keyspaces

Database statuses

Your database can exist in a range of statuses. These statuses vary based on the actions you take within your database.

To see the system status of Astra, see https://status.astra.datastax.com/.

To see the status of a specific database, view your database Dashboard.

All databases

Active

Your database is available and ready to use.

Initializing

You’ve made your database selections. It should be ready for you to use soon.

Terminating/Terminated

You have terminated your database, which means your database and all data on your database will be removed. Your database is no longer available.

Error

Something is wrong with your database. Contact DataStax Support.

Maintenance

When a database is moving into hibernated or restarting from hibernated, your database will display that it is in the Maintenance status.

Hibernated

When an Astra DB database on the Free plan has been unused for more than 48 hours, it will automatically enter the Hibernated status.

It may take a few minutes for your hibernated Astra DB database to resume (return to Active status).

Database hibernation only occurs on the Free plan. Hibernated does not occur on the Astra DB paid plans. To avoid Hibernated, and to take full advantage of additional Astra DB functionality, upgrade from the Free plan to a Pay As You Go plan, or to an Enterprise plan. For details, see Pricing and billing.

To view the status of any database within your organization,

Open your Astra DB dashboard.
1. If you have more than one database in a hibernated status, a banner appears at the top of the screen prompting you to click Resume Databases.
To activate a specific database, navigate to the Databases table on your dashboard. Select the database(s) to activate.
1. Click Resume to activate a hibernated database.
2. Hover Hibernated for a quick definition of this term.
3. Click the database name to open it, but remain in the hibernated status.

Monitor your databases

View connection details, performance metrics, and health details for databases in your organization.

The Databases page provides an overview of all databases in your organization, including the databases you created and databases created by other team members. However, only a database creator can make changes to a database and view its connection details, which can be shared manually with other team members.

View your databases

View all databases in your organization, and select a database to view detailed information about the database.

Selecting a database in DataStax Astra DB provides access to detailed information about the database. You can view the keyspaces, size and location of the database, and the estimate cost per hour.

Open a browser, navigate to Astra DB, and log in.
Select a database from the Databases option in the left navigation or from Recent Resources on the home page.
Click the Overview tab.

You can only view connection details and database management operations for databases that you created.
You can see several database details from this tab:
- Database Name
- Status
- Usage for current billing period
  - Read Requests
  - Write Requests
  - Storage Consumed
  - Data Transfer
- Compute Size [Only for Classic tier databases]
- Replication Factor [Only for Classic tier databases]
- Current Capacity [Only for Classic tier databases]
- Regions
  - Provider
  - Area
  - Region
  - Datacenter ID
  - Region Availability
- Keyspaces

View health and metrics

Select a database to view health metrics and performance information. When selecting a database, you can view health metrics that include information regarding latency and throughput to the database. These metrics provide insights into the performance of the database and how workloads are distributed.

When viewing information about a database on the Health page, select the region from the dropdown available at the right to view the health metrics of the database particular to that region. This is only applicable for multi-region databases.

View health dashboard

Open a browser, navigate to DataStax Astra DB, and log in.
On the Databases page, select the database name to view details for. Details for the database display on the Overview tab.
To view health metrics for the database, select the Health tab.
Select the time period to display in the health metrics for.

View health dashboard in full window

Select Cycle View Mode in the upper right corner. This selection displays the cycle view.
Press Esc.
Select the share icon in the upper left corner.
Copy the URL.
Paste the URL in a new browser tab or window to see the dashboard.

Results

Metrics for the database display in the Grafana dashboard embedded in Astra Portal. To view more granular metrics, hover over a specific time in the graph. Read and write latencies display in nanoseconds.

Request Overview

Requests Combined

Displays request rates (req/s) for different types of requests. The rates are summed over all database coordinators.

Request Errors

Displays the request error rates (req/s) for different types of requests. The rates are summed over all database coordinators.

Timeouts indicate that the queries are taking too long to complete.
Unavailables indicate that the coordinator did not have enough alive data nodes to work with.
Failures can be caused by queries violating certain guardrails or other error conditions. For more, see Astra DB database guardrails and limits.

Writes

Write Latency: Displays coordinator write request latency quantiles on the left y-axis and the total write request rate (req/s) on the right y-axis.
Write Size Distribution: Displays different write request mutation size quantiles. Large mutations can cause performance problems and might even be rejected.

Reads

Read Latency: Displays coordinator read request latency quantiles on the left y-axis, and the total read request rate (req/s) on the right y-axis.
Range Latency: Displays coordinator range request latency quantiles on the left y-axis, and the total range request rate (req/s) on the right y-axis.

Stargate

Stargeate

Connected Clients: Displays the number of CQL connections

Lightweight Transactions (LWTs)

health lwt

Column Access Strobe (CAS) Write Latency: Displays coordinator CAS write request latency quantiles on the left y-axis, and the total CAS write request rate (req/s) on the right y-axis.
CAS Write Contention: Displays coordinator CAS write request contention quantiles on the left y-axis and the number of unfinished commits on the right y-axis.

A high number of contended requests negatively affect request latency and cause timeouts. Reduce the number of concurrent requests to the same partition. Unfinished commits cause increased latency. Reducing contention can help reduce the number of unfinished commits.

CAS Read Latency: Displays coordinator CAS read request latency quantiles on the left y-axis, and the total CAS read request rate (req/s) on the right y-axis.
CAS Read Contention: Displays coordinator CAS read request contention quantiles on the left y-axis, and the number of unfinished commits on the right y-axis.

Tombstones

Tombstones Scanned / s: Displays the number of tombstones being scanned per keyspace, table, and second. A large number of tombstones can cause increased latency or query failures.
Tombstone Guardrail Warnings / s: Displays the number of queries exceeding the tombstone guardrail warning threshold per keyspace, table, and second. For more, see Astra DB database guardrails and limits.
Tombstone Guardrail Failures / s: Displays the number of queries exceeding the tombstone guardrail failure threshold per keyspace, table, and second. For more, see Astra DB database guardrails and limits.

Export Astra DB metrics to an external system

Enterprises depend on the ability to view database health metrics in centralized systems along with their other software metrics. The Astra DB Metrics feature lets you forward Astra DB database health metrics to an external third-party metrics system. We refer to the recipient of the exported metrics as the destination system.

Use Astra Portal or DevOps API to export metrics

You can export Astra DB health metrics via Astra Portal or the DevOps API. For details, see:

Supported destinations

Astra DB supports exporting health metrics from its serverless databases to:

You can also use Grafana or Grafana Cloud as a visualization tool.

Feature availability

The Astra DB Metrics feature:

Is available only for Astra DB serverless databases.
Is available only with Pay As You Go (PAYG) or Enterprise.
Is not available on the Astra DB Free plan.

Free plan users: in Astra Portal, login and click the Chat icon. It’s on the lower-right corner of the page. Ask the DataStax representative about upgrading your organization to a paid plan, so that you can use Export Metrics and many other Astra DB features.

Manage access list for public endpoints

Use access lists to limit what public endpoints are able to access your database. You can choose to restrict access in one of two ways:

Restrict access to specific IP addresses
Restrict access to a range of IP addresses using Classless Inter-Domain Routing (CIDR)

When Access List is configured and active, access to these endpoints is restricted:

CQL, GraphQL, and REST
GraphQL Playground
Swagger
CQLsh

You can also manage your access list using the DevOps API.

If you are using the access list and restricting public access, these restrictions exclude the Astra internal site reliability controls.

Only Organization and Database Administrators for the database have permissions to manage the access list.

Restrict public access

By default, public access to your database is not restricted. Access to your database is possible via public internet.

In your database Settings, select the toggle to restrict public access.
Confirm your selection to Restrict Public Access.

Until you add an address to your access list, public access is still available.

Add IP address or CIDR to access list

Ensure public access is restricted.
Select Add Access.
Select Add new endpoint.

Select IP Address or CIDR from the Type menu.

A CIDR indicates a range of IP addresses. For example, the CIDR range '192.168.0.0/16' represents the first IP address of '192.168.0.0' through the last IP address of '192.168.255.255'. The '/16' mask indicates that the first 16 bits of the IP address are static. The addresses in the CIDR range are represented by all the permutations of the last 16 bits.

Enter the IP address or CIDR into the Address field.

If you want to add you current IP address, copy it from the display and paste it into the Address field.

All IP address must be entered in the IPv4 format, which is four decimal numbers, each ranging from 0 to 255. For example, 179.46.234.11.
Optional: Add a description for the address you are adding. For example, office or home.
Select Add to add the address to the access list.

It takes approximately five minutes for each address to sync and have access.

Upload list of endpoints

Ensure public access is restricted.
Select Add Access.

Select Upload from file.

[
  {
    "address": "10.0.0.1",
    "description": "Reader"
  },
  {
    "address": "10.0.0.1/32",
    "description": "Librarians"
  }
]

Use the Select File button to find the JSON file with your access list to upload.

You will see the list of addresses to be added to the access list.
Select Import to add the addresses to your access list.

Import endpoints from database

You can import an access list from another Astra database. If you do not have another active Astra database, this option will not be available.

Ensure public access is restricted.
Select Add Access.
Select Import from database.
Select the active Astra database from which you want to import the addresses.

You will see the list of addresses to be added to the access list.
Select Import to add the addresses to your access list.

Enable or disable an endpoint

Select the overflow menu for the address you want to enable or disable.
Select Enable or Disable.

The overflow menu will show the Disable option only when the address is enabled and the Enable option only when the address is disabled.
Confirm your selection to Enable or Disable the endpoint.

Your access list remains active, even if all endpoints are disabled. If you want to allow public access, you must select the toggle to stop restricting public access.

Delete an endpoint

If you remove all of the addresses on your access list, your database will be accessible from the public internet, even if Restrict public access is selected.

Select the overflow menu for the address you want to remove.
Select Delete.
Confirm your selection to Delete the endpoint.

It takes approximately five minutes for each address to sync and be removed from the access list.

Allow public access

If you stop restricting public access, access to your database is possible via public internet.

Select the toggle to stop restricting public access.
Confirm your selection to Enable public access.

Manage multiple keyspaces

In Astra, keyspaces hold the datacenter names associated with your Astra regions and defines the replication factor (3 for writes in LOCAL_QUORUM) for each datacenter. A replication factor of 3 ensures against losing your data. You can create keyspaces either with the Astra Dashboard or the DevOps API. Use the instructions below to delete a keyspace with your Astra account, if necessary.

Creating a database with multiple keyspaces allows you to create different data models for each keyspace or store unique data in unique keyspaces. Multiple keyspaces within a single region allows for an application built on a per-keyspace data model.

Adding a new keyspace

Open a browser, navigate to Astra DB, and log in.

On the Dashboard page, select the database name to access the Overview page for your selected database.

Select Add Keyspace.

Enter the new keyspace name. When creating your new keyspace name, make sure you meet the following requirements:
- No empty spaces or null
- A maximum of 48 characters
- Only use alphanumeric characters and/or underscores

Select Save.

Your list of keyspaces displays on the Overview page for your database.

Deleting a keyspace

If you delete a keyspace, all data in that keyspace is removed and cannot be recovered.

Open a browser, navigate to DataStax Astra DB, and log in.

On the Dashboard page, select the database name to access the Overview page for your selected database.

Select the overview menu (…) for the keyspace you want to delete.

Select Delete.

In the Delete keyspace menu, type in the name of the keyspace to delete.

Select Delete Keyspace.

Your list of keyspaces will be updated on the Overview page to show only the remaining keyspaces for your database.

Using multiple regions

You can replicate data to multiple regions for high availability scenarios to ensure active-active applications failover models. Multiple regions also ensure application data availability for locality purposes with the added value of cost savings.

Having multiple regions may increase your billing. For more, see Pricing and billing.

Video introduction

See this short video introduction to the Astra DB multi-region implementation:

Eventual consistency model and multi-region updates

DataStax Astra DB follows the eventual consistency model. Depending on the selected consistency level, data written to one region might not be immediately accessible to other regions in the same database.

If you are using the EACH_QUORUM consistency level for normal updates or SERIAL consistency level for Lightweight Transactions (LWT), then data is immediately accessible on all regions provided the operation successfully completes. These consistency levels are for only write requests.

For all other consistency levels, data might not be immediately accessible. The time span is normally within a few minutes to fully replicate the data. However, it could take longer, and possibly span one or more days. There are several contributing factors to the latter scenario, such as the workload volume, the number of regions, the data repair operations, and network resources.

For more, see the FAQs in this topic.

Serverless databases

Multiple regions is available on only pay as you go and annual plans.

If you are adding multiple regions to your database, you can use each region only once. You cannot add the same region to the same database more than one time.

Add a new region to your database

From your database’s Dashboard, select Add Region.
Select your desired region from the dropdown menu of available choices.

You can review your selected region and its cost below the dropdown menu.

You can add only a single region at one time.
Select Add Region to add the region to your database.

After you add the new region, your new region appears in the list of regions on your database dashboard. Your existing region status will change to Maintenance, but will still be available for operations.

The information displayed on the Connect page for your database is region specific.

Delete a region from your database

The information displayed on the Connect page for your database is region specific.

Removing a region is not reversible. Proceed with caution.

From you database Dashboard, select the overflow menu for the database you want to delete.
Select Delete.
Type "delete" in the text bar.
Select Delete to delete your region.

Limitations

If there are network issues between regions, the following operations might not be available or have limited availability:

Schema changes
Table truncation
Lightweight transactions
Data repair

While adding a new region, you cannot drop a table or keyspace and you cannot truncate a table.

Data sovereignty

Astra DB serverless replicates all data in the database to all of a database’s regions. By contrast, multiple keyspaces in Apache Cassandra® and DataStax Enterprise (DSE) allow a database to replicate some tables to a subset of regions. To achieve the same behavior as Cassandra or DSE, create a separate Astra DB instance that adheres to the necessary region restrictions. The database client will need to add a separate connection for the additional database and send queries to the appropriate connection depending on the table being queried.

Astra DB Serverless multi-region FAQ

While creating an Astra DB database, can I select multiple regions?

No. The workflow is to create a database with a selected region; then once the launched database reaches an Active status, you may add a region.

How many regions can I add?

The only limitation is the number of regions that are available in Astra DB. See Database Regions for the list of supported regions.

How many regions can I add or remove at a time?

The current implementation allows one addition or removal at a time.

How quickly are updates applied to all regions in the same database cluster?

It depends on several factors. Astra DB follows the eventual consistency model. As a result, data written to one region might not be immediately accessible within other regions in the same database cluster. The time span is normally within a few minutes to fully replicate the data. Several contributing factors can extend this time, such as the workload volume, the number of regions, and network resources.

On rare occasions, a write request might succeed in one region, but fail in another region. The time taken to repair the inconsistency determines the speed of the replication. The repair cycle for inconsistencies between regions can take anywhere from minutes to several hours to run. If the network between the two regions is broken, correcting the inconsistencies can take days.

Can I remove a region that I no longer need?

Yes, this action is supported with Astra DB Serverless. Exception: you cannot remove the original region selected when you created the Astra DB database. The original region can be deleted after all other regions are deleted by using the Terminate database operation.

Will I lose data when I remove a region?

No. All data in the datacenter is replicated prior to being decommissioned.

Can I park a region?

No. The best option, in this case, is to remove the region.

Can I specify replication rules by keyspace?

By default, replication is applied at the database level. With Astra DB Serverless, there is no upfront database setup costs. The replication goal may be addressed by separating workloads by database without an impact on costs.

Is the Access List configuration by region?

The Access List configuration applies at the database level.

How are backups managed?

Backups are taken on the region in which the database was first created.
The restore process follows this workflow: restore to the original region, and then add the other regions.
For help with restore, please contact DataStax Support.

What’s next?

See additional database management topics.

Terminating your database

When you no longer need a database, terminate it to reduce costs and streamline operations. When you terminate a database, all data is permanently deleted and cannot be recovered.

If you have administrator privileges in the DataStax Astra Portal for your team, you can contact DataStax to terminate databases that are owned by other team members. For example, if a team member leaves your organization and you want to delete their databases, contact DataStax with the names of the databases owned by that team member.

Procedure

See instructions on how to terminate a multi-region database here.

Open a browser, navigate to Astra DB, and log in.
From the Dashboard page, select the overflow menu for the database you want to terminate and select Terminate.

All data in the database will be permanently deleted. You cannot restart the database. Proceed with caution.
To terminate the database, type in the database name you want to terminate and select Terminate.

Results

Your database is removed from the list of available databases. You will receive an email when your database is successfully terminated.