Configure multiple regions for a database

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 Subscriptions and billing.

Data consistency

Astra DB follows the eventual consistency model. Data is queried from the primary region, which is the region selected when creating the database. If a write request succeeds, data is immediately accessible in all regions when using the following consistency levels:

EACH_QUORUM for normal updates.
SERIAL for Lightweight Transactions (LWT).

For all other consistency levels, data written to one region might not be immediately accessible in other regions in the same database. Normally, it takes up to a few minutes to replicate this data. However, several factors might extend this time, such as workload volume, the number of regions, and network resources.

On rare occasions, a write request might succeed in one region but fail in another. In such scenarios, the time taken to repair the inconsistency determines the speed of replication. The repair cycle can take anywhere from a few minutes to several hours. If there’s a network disruption between regions, correcting the inconsistencies can take days.

If a network disruption occurs between regions, the following operations might have limited or no availability:

Schema changes
Table truncation
Lightweight transactions
Data repair

For more information, see Use a multi-region database.

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, go to Databases, and then select your database.
On the Overview tab, in the Regions section, click Add Region.
Select a region to add to your database. The following restrictions apply:
- You can add only one region at a time.
- You can’t 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 can’t 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 --location -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 can’t 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 can’t 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 --location -X GET "https://api.astra.datastax.com/v2/regions/serverless?region-type=vector" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Accept: application/json"

A successful request returns 201 Created.

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

While in Maintenance status, you can’t 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 can’t 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, you must use the Data API to create collections or load data into regions other than the primary region. In the Astra Portal, you can create collections and load data into the primary region only, which is the region you selected when you created the database. However, because multi-region databases follow an eventual consistent model, data loaded into any region is eventually replicated to the database’s other regions.

List database regions

Astra Portal
DevOps API

In the Astra Portal, go to Databases, and then select 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. 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 --location -X GET "https://api.astra.datastax.com/v2/databases/DB_ID/datacenters" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Accept: application/json"

To get the DB_ID, see Get your database ID.

Response

The response includes information about the database. For multi-region databases, the response includes all of the regions where the database is deployed.

[
  {
    "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, go to Databases, and then select your database.
On the Overview tab, in the Regions section, locate the region that you want to inspect.
Click more_vert More Options, 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 can’t remove the primary region, which is the first region selected when you created the database.

Astra Portal
DevOps API

In the Astra Portal, go to Databases, and then select your database.
On the Overview tab, in the Region section, locate the region you want to delete, click more_vert More Options, 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. You can delete only one region at a time.

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

To get the DATACENTER_ID, see List database regions.

A successful request returns 202 Accepted.

The database enters Maintenance status while deleting the region.