Create a 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 exclusively for non-vector data. You can load vectors directly with your data or automatically generate vector embeddings with vectorize.

For Retrieval Augmented Generation (RAG) applications, such as chatbots, agents, support bots, sentiment analysis, personalization, and multi-media search, use a Serverless (Vector) database.

Serverless (Non-Vector) databases

Designed for generic applications, such as content management, user authentication, and transactional applications.

For more information, see Intro to Astra DB Serverless and Intro to vector databases.

To create databases, you must have the appropriate permissions, such as the Organization Administrator or Database Administrator role. To programmatically create databases, you need an application token with sufficient permissions.

  • If you plan to bring your own encryption keys, you must create and register your customer keys before creating databases.

  • Organizations on the Free plan can’t have more than five databases.

Create a Serverless (Vector) database

After you sign in to the Astra Portal, you can navigate directly to https://db.new/ to start creating a new database.

  • Astra Portal

  • API/CLI

  1. In the Astra Portal navigation menu, click Databases, and then click Create Database.

  2. Select the Serverless (Vector) deployment type.

  3. Enter a meaningful, human-readable Database name.

    After you create a database, you can’t change its name.

    Database names are permanent. They must start and end with a letter or number, and they can contain no more than 50 characters, including letters, numbers, and the special characters & + - _ ( ) < > . , @.

  4. Select a 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.

  5. 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, load data, and connect to your database.

Create a Serverless (Non-Vector) database

After you sign in to the Astra Portal, you can navigate directly to https://db.new/ to start creating a new database.

  • Astra Portal

  • API/CLI

  1. In the Astra Portal navigation menu, click Databases, and then click Create Database.

  2. Select the Serverless (Non-Vector) deployment type.

  3. Enter a meaningful, human-readable Database name that meets the following requirements:

    • Starts and ends with a letter or number.

    • Contains only letters, numbers, and the following special characters: & + - _ ( ) < > . , @.

      After you create a database, you can’t change its name.

  4. In the Keyspace name field, enter a name for the database’s first keyspace. Choose a name that reflects your data model and meets the following requirements:

    • Only alphanumeric characters and underscores

    • No more than 50 characters

    • Isn’t dse or system

  5. Select a Provider and Region.

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

  6. 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, load 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, select Databases to see a list of all of your databases along with their IDs.

  • In the navigation menu, select 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 DB organization. If the supplied token doesn’t have permission to view a particular database, the response won’t include any information for that database.

Response

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

  1. In the Astra Portal, go to Databases, and then select your database.

  2. 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 -L -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"
  }
]

See also

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com