Create an Astra DB Serverless database

Astra DB Serverless is a fully managed serverless database-as-a-service (DBaaS) that is 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 (gen AI) 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?.

You can create both types of databases in the Astra Portal, with the DevOps API, Data API clients, and the Astra CLI.

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 database in the Astra Portal

You can create Serverless (non-vector) and Serverless (vector) databases in the Astra Portal:

In the Astra Portal, click Create database.
Click Serverless (vector) or Serverless (non-vector).

DataStax recommends Serverless (vector) for most use cases. It supports all the same features as Serverless (non-vector) with added support for vector data, vector search capabilities, and the Data API.
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
Serverless (non-vector) databases only: 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
For Serverless (vector) databases, the first keyspace is automatically named default_keyspace.
Select a cloud 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.

For multi-region availability, you can add more regions after you create the database.
If applicable to your Astra organization, you can select or create a PCU group for the database.
Click Create database.

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

Create a database with the DevOps API

To create a Serverless (non-vector) and Serverless (vector) database with the DevOps API, use POST /v2/databases:

Serverless (vector) database

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,
  "pcuGroupUUID": "PCU_GROUP_ID"
}'

Serverless (non-vector) database

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

Replace or set 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: Optional name for the database’s first keyspace. If empty or omitted, the first keyspace is named default_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: An unlocked region that supports the database type you want to create.

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.

For multi-region availability, you can add more regions after you create the database.
You can use the DevOps API or a Data API client to list available regions. For more information, see the following:

Find available regions

GET /v2/regions/serverless
dbType: Determines the type of database to create:
- To create a Serverless (vector) database, dbType must be vector.
- To create a Serverless (non-vector) database, omit dbType or set it to an empty string.
tier: Must be serverless for all Astra DB Serverless databases.
capacityUnits: Must be 1 for all Astra DB Serverless databases. This setting is unrelated to PCU group capacity.
PCU_GROUP_ID: If your organization uses PCU groups, you can provide a pcuGroupUUID in your DevOps API request body to assign the database to the specified PCU group. The specified PCU group must have the same cloudProvider and region as the database.

To create the database without assigning it to a PCU group, omit the pcuGroupUUID parameter.

For more information, see Create a database.

Create a database with the Astra CLI

You can use the Astra CLI astra db create command to create Serverless (non-vector) and Serverless (vector) databases.

The Astra CLI doesn’t support PCU group assignment with database creation. To add a database to a PCU group during database creation, you must use the DevOps API or Astra Portal to create the database.

Create a database with the Data API clients

You can use the Data API clients to create Serverless (non-vector) and Serverless (vector) databases. For more information and examples, see Create a database.

The Data API clients don’t support PCU group assignment with database creation. To add a database to a PCU group during database creation, you must use the DevOps API or Astra Portal to create the database.

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.

Get database details

After you create an Astra DB Serverless 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

The Astra Portal dashboard shows a summary of your organization’s Astra DB Serverless databases. To inspect a specific database, click the database’s name.

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, you can 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 ID with the Data API clients

See Find all databases.

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

Get a database Data API endpoint

Get a Data API endpoint in the Astra Portal: In the Astra Portal, click the name of the Serverless (vector) database that you want to connect to. The Data API endpoint for your database is listed under the Database Details section.
Get a Data API endpoint with the Astra CLI: See astra db endpoints data-api.

Next steps

Once your database reaches Active status, you can load data and integrate your database into your applications. Try these next steps: