Create an Astra DB Serverless database

Astra DB Serverless is a fully managed serverless database-as-a-service (DBaaS), powered by Apache Cassandra®, an open-source NoSQL distributed database.

Astra DB Serverless offers two types of serverless databases:

Serverless (Vector) databases: Designed for vector search applications, such as Generative AI (GenAI) and semantic search, with support for non-vector use cases. You can store vectors alongside non-vector data or create collections and tables exclusively for non-vector data. You can load vectors directly with your data or automatically generate vector embeddings with vectorize.

Use Serverless (Vector) databases for Retrieval Augmented Generation (RAG) applications, such as chatbots, agents, support bots, sentiment analysis, personalization, and multi-media search.
Serverless (Non-Vector) databases: Designed for generic applications, such as content management, user authentication, and transactional applications.

For more information, see About Astra DB Serverless and What are vector databases?.

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 a Serverless (Vector) database

Astra Portal
API/CLI

Sign in to the Astra Portal, and then click Create a Database.
Select the Serverless (Vector) deployment type.
Enter a meaningful, human-readable database name.

Database names are permanent. After you create a database, you cannot change its name.
Rules for database names
- Must start and end with a letter or number
- Can contain letters, numbers, and the special characters & + - _ ( ) < > . , @
- Cannot exceed 50 characters
Select the Provider and Region to host your database.

On the Free plan, you can access a limited set of supported regions. To access Locked regions, you must upgrade your subscription plan.

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

New databases start in Pending status, and then move to Initializing. Your database is ready to use when it reaches Active status.

You can use the DevOps API, the Data API clients, and the Astra CLI to create databases programmatically.

For example, to create a Serverless (Vector) database, you can use the following curl command:

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": "",
  "cloudProvider": "CLOUD_PROVIDER",
  "region": "REGION",
  "dbType": "vector",
  "tier": "serverless",
  "capacityUnits": 1
}'

For more information, including examples and parameters, see the Databases API reference.

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"

Once active, you can create collections, insert data, and connect to your database.

Create a Serverless (Non-Vector) database

Astra Portal
API/CLI

Sign in to the Astra Portal, and then click Create a Database.
Select the Serverless (Non-Vector) deployment type.
Enter a meaningful, human-readable database name.

Database names are permanent. After you create a database, you cannot change its name.
Rules for database names
- Must start and end with a letter or number
- Can contain letters, numbers, and the special characters & + - _ ( ) < > . , @
- Cannot exceed 50 characters
In the Keyspace name field, enter a name for the database’s first keyspace.
Rules for keyspace names
- 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 the Provider and Region to host your database.

On the Free plan, you can access a limited set of supported regions. To access Locked regions, you must upgrade your subscription plan.
Click Create Database.

New databases start in Pending status, and then move to Initializing. Your database is ready to use when it reaches Active status.

You can use the DevOps API, the Data API clients, and the Astra CLI to create databases programmatically.

For example, to create a Serverless (Non-Vector) database, you can use the following curl command:

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": "serverless",
  "capacityUnits": 1
}'

For more information, including examples and parameters, see the Databases API reference.

Once active, you can create tables, insert data, and connect to your database.

Get your database ID

Astra Portal
DevOps API

In the Astra Portal, you can do either of the following:

In the navigation menu, click Databases to see a list of all of your databases along with their IDs.
In the navigation menu, click a specific database. The Database ID appears under the database name and in the page URL:

astra.datastax.com/org/ORGANIZATION_ID/database/DATABASE_ID/.

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 "Accept: 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.

Result

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.

[
  {
    "id": "FIRST_DB_ID",
    "orgId": "organizations/ORG_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_DB_ID",
    "orgId": "organizations/ORG_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 region ID (datacenter ID)

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"
  }
]

Troubleshoot database limit error

If you are unable to create a database due to reaching the database limit, check your organization’s subscription plan. Organizations on the Free plan cannot have more than five databases.