Deploy an Astra DB Serverless database to multiple regions

You can configure a database to replicate data across multiple regions. Some benefits of multi-region databases include better data locality and higher availability for multi-region application architectures.

Multi-region databases are a premium feature. Each region added to a database increases the database’s costs. This includes a one-time data replication fee for the new region, and charges for replicating data to all database regions. For more information, see Astra DB Serverless billing and usage.

Data consistency

Astra DB Serverless replicates data across three availability zones within each deployed region to promote uptime and ensure data integrity.

Astra DB follows the eventual consistency model, and you cannot independently manage, restrict, or modify replicas. When you deploy a database to an additional region, data is queried and replicated from the primary region, which is the region selected when you created the database. When you write to a multi-region database, the data is eventually replicated to all regions where the database is deployed, regardless of the initial write region.

The time required to replicate data across all regions and availability zones depends on the number of regions, workload volume, and network resources. Generally, data replication takes minutes, but it can take hours or days if there are failures or outages.

Consistency levels

Consistency levels determine the number of replicas that must acknowledge a read or write operation before it’s considered successful.

The Data API and clients always use the LOCAL_QUORUM consistency level for reads and writes.

With CQL and drivers, you can use all read consistency levels and all write consistency levels except ONE, ANY, and LOCAL_ONE. For more information about supported consistency levels, see the CQL documentation on CONSISTENCY.

LOCAL_QUORUM is generally sufficient for balanced workloads due to Astra DB’s eventual consistency model. It has lower latency than multi-region consistency levels because it only requires acknowledgement from replicas in the target read/write region.

If you want to ensure that a write request has written to all of a database’s regions before considering it successful, you might use EACH_QUORUM, SERIAL, or ALL. However, these consistency levels have higher latency than LOCAL_QUORUM because they require acknowledgement from replicas in all regions. ALL has the highest latency because it requires acknowledgement from all replicas in all regions.

Repair cycles

If a write request succeeds in one region and fails in another, Astra DB attempts to repair the inconsistency.

Generally, repair cycles range from a few minutes to a few hours, but they can take days if a network disruption occurs between regions.

Network disruptions can limit or prevent the following operations:

Schema changes
Table truncation
Lightweight transactions
Data repair

Add a region to a database

To manage regions, you must have the appropriate permissions, such as the Manage Region permission. To programmatically manage regions, you need an application token with sufficient permissions.

Astra Portal
DevOps API

In the Astra Portal navigation menu, click Databases, and then click the name of your database.
On the Overview tab, in the Regions section, click Add Region.

If this button is disabled, check the following:
- You have the Manage Region permission.
- The database is in Active status.
- CDC is not enabled on the database. If CDC is enabled, you must use the DevOps API to add a region.
Select a region to add to your database. The following restrictions apply:
- You can add only one region at a time.
- You cannot select a region that the database already uses.
- You must select a region in the same cloud provider as the database’s other regions. Multi-region databases cannot span multiple cloud providers.
- For Serverless (Vector) databases, you must select a region that supports that database type. For more information, see Astra DB Serverless database regions and maintenance schedules.
Click Add Region.

You can use the DevOps API to add a region to a database. You can add only one region at a time.

curl -sS -L -X POST "https://api.astra.datastax.com/v2/databases/DB_ID/datacenters" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Accept: application/json" \
--data '{
  [
    {
      "tier": "serverless",
      "cloudProvider": "GCP",
      "region": "us-east1"
    }
  ]
}'

tier and cloudProvider must be the same as the database’s primary tier and cloud provider. You can use the Find database by ID endpoint to get these values.

region must be a valid region:

You cannot select a region that the database already uses.
You must select a region in the same cloud provider as the database’s other regions. Multi-region databases cannot span multiple cloud providers.

For Serverless (Vector) databases, you must select a region that supports that database type. For more information, see Astra DB Serverless database regions and maintenance schedules.

You can use the DevOps API to Get available regions for Astra DB Serverless databases. Use the optional region-type query parameter to get supported regions for Serverless (Vector) databases only.

curl -sS -L -X GET "https://api.astra.datastax.com/v2/regions/serverless?region-type=vector" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Accept: application/json"

If CDC is enabled, you must include the streamingTenant object to configure CDC for the new region. For an example and more information, see Enable CDC on a table, specifically the DevOps API: Deploy a secondary region with CDC enabled option.

The database enters Maintenance status while provisioning and replicating data to the new region.

While in Maintenance status, you cannot add or remove regions, truncate tables, or delete keyspaces, tables, or collections.

Maintenance status doesn’t impact reads and writes.

Use a multi-region database

There are a few operational differences when using a multi-region database as compared to a single-region database:

The database’s CQL Console only connects to one region at a time. You can find the currently-connected region at the top of the CQL Console. You can use the Region menu above the CQL Console to switch between available regions.
Each region has its own Secure Connect Bundle (SCB).
You cannot replicate data, including keyspaces, collections, or tables, to a specific subset of regions. Astra DB replicates all data in the database to all of a database’s regions. For more information, see Data consistency.

If you need to limit data to specific regions, you must load that data into a separate database that adheres to the necessary region restrictions. Make sure your database client has a separate connection for the additional database and that it sends queries to the appropriate connection based on the table being queried.
For multi-region databases, the Astra Portal’s Data Explorer accesses and manipulates keyspaces, collections, tables, and data from the primary region. If you need to manage your database from a secondary region, you must use the Data API or CQL. Generally, accessing secondary regions is for latency optimization when the primary region is geographically distant from the caller or when the primary region is experiencing an outage. However, because multi-region databases follow an eventual consistent model, changes to data in any region are eventually replicated to the database’s other regions.

List database regions

Astra Portal
DevOps API

In the Astra Portal navigation menu, click Databases, and then click the name of your database.
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.

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/DB_ID/datacenters" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Accept: application/json"

Result

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.

[
  {
    "id": "1234-5678-91011121-3141-1",
    "name": "dc-1234-5678-91011121-3141",
    "tier": "serverless",
    "status": "ACTIVE",
    "cloudProvider": "GCP",
    "region": "us-east1",
    "regionZone": "na",
    "regionClassification": "standard",
    "capacityUnits": 1,
    "grafanaUrl": "http://path-to-grafana:port",
    "cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
    "graphqlUrl": "http://path-to-graqphl:port/api/graphql",
    "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"
  }
]

Inspect region usage

In the Astra Portal navigation menu, click Databases, and then click the name of your database.
On the Overview tab, in the Regions section, find the region that you want to inspect.
Click More, and then select Details to open the Region Details pane.

Delete a region from a database

When you remove a region, any connections to the deleted region are also removed. However, to avoid data loss, all data is replicated before the region is deleted.

You cannot remove the primary region, which is the first region selected when you created the database.

Astra Portal
DevOps API

In the Astra Portal navigation menu, click Databases, and then click the name of your database.
On the Overview tab, in the Region section, find the region you want to delete, click More, and then select Delete.

You can delete only one region at a time.
In the confirmation dialog, enter delete, and then click Delete Region.

You can use the DevOps API to remove a region from a database:

curl -sS -L -X DELETE "https://api.astra.datastax.com/v2/databases/DB_ID/datacenters/DATACENTER_ID/terminate" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Accept: application/json"

You can delete only one region at a time. To get the DATACENTER_ID, see List database regions.

A successful request returns 202 Accepted.

The database enters Maintenance status while deleting the region.