Create a database

Databases store data for your applications.

A paid database starts with the following specifications:

  • A single region

  • A single keyspace

  • Storage based on your subscription plan

  • Capacity for up to 200 tables

  • Replication factor of three to provide optimal uptime and data integrity

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

Create a database in the Astra Portal

To create and launch an Astra DB Classic database, do the following:

  1. In the Astra Portal, go to Databases, and then click Create Database.

  2. Select the Classic deployment type.

  3. Enter a meaningful database name.

    You can’t change the database name after you create the database.

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

  4. Enter a name for the database’s initial 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 cloud provider and region.

    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.

  6. Select a Workload Type and Workload Size for this database. For more information, see workload capacity tiers for this database.

  7. In the Total Cost section, review the estimated hourly cost.

    DataStax offers $25.00 in free Astra DB credits per month for organizations on the Free plan.

  8. Click Create Database to initiate database creation.

    It can take several minutes to initialize the database. DataStax sends you an email notification when your database is ready to use.

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

Create a database with the DevOps API

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

For example, the following curl command creates an Astra DB Classic 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"
  "tier": "WORKLOAD_PLAN",
  "capacityUnits": CAPACITY_UNITS
}'

Replace the following:

  • APPLICATION_TOKEN: An application token with the necessary permissions to create databases.

  • DATABASE_NAME: The desired name for the database.

  • KEYSPACE_NAME: The name for the database’s initial keyspace.

  • CLOUD_PROVIDER: One of 'aws', 'gcp', or 'azure'.

  • REGION: A valid cloud provider region, depending on your subscription plan and the database type.

    You can use the DevOps API to Get supported regions, tiers, and capacity.

    curl -sS -L -X GET "https://api.astra.datastax.com/v2/availableRegions" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Accept: application/json"

  • WORKLOAD_PLAN: Provide a valid workload capacity tier for the database. One of developer (free), C20, C40, D10, D20, or D40.

    For C40i and E tier plans, use the Astra Portal to create the database.

  • CAPACITY_UNITS: The initial number of capacity units for the database. This is the amount of space available (horizontal scaling) for the database. For developer, the max is 1. For C and D tier, the max is 12 on startup.

A successful request returns 201 Created and the database ID. It takes several minutes for the database to initialize and reach ACTIVE status. Once active, you can create keyspaces and tables, load data and connect to your database.

For multi-region databases, use the DevOps API Add datacenters endpoint to deploy additional regions.

Get database details

After you create a database, you can get information about it, such as its database ID, status, regions, and usage.

  • Astra Portal

  • DevOps API

In the Astra Portal navigation menu, click Databases to view a summary of your organization’s databases, which includes databases that you create and databases that your team members create.

To view or manage a specific database, click the database’s name. Database details include:

  • Database name and ID

  • Status

  • Usage for current billing period, including reads, writes, storage, and data transfer

  • Compute Size (only for Classic tier databases)

  • Replication Factor (only for Classic tier databases)

  • Current Capacity (only for Classic tier databases)

  • Region details, including the provider, area, region name, datacenter ID, and region availability

  • Keyspaces

The Astra Portal only shows connection details and database management operations for databases you create or have permission to administer.

You can use the DevOps API to get information about one database or get information about all databases in an organization.

To get information about a specific database, use GET /v2/databases/DB_ID. The provided application token must have sufficient permissions to perform the requested operations, such as the Database Administrator role.

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases/DB_ID" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
Response

A successful request returns 200 Created and an object containing database information.

This example response is truncated for brevity.

{
  "id": "DB_ID",
  "orgId": "organizations/ORG_ID",
  "ownerId": "users/USER_ID",
  "info": {
    "name": "DB_NAME",
    "keyspace": "INITIAL_KEYSPACE_NAME",
    "cloudProvider": "CLOUD_PROVIDER",
    "region": "REGION",
    "additionalKeyspaces": [
      "SECOND_KEYSPACE_NAME"
    ],
    "dbType": "vector"
  },
  "creationTime": "2012-11-01T22:08:41+00:00",
  "terminationTime": "2019-11-01T22:08:41+00:00",
  "status": "ACTIVE",
  # Response truncated for brevity
}

To get information about all databases in an organization, use GET /v2/databases. The provided application token must have sufficient permissions to perform the requested operations, such as the Organization Administrator role. Additionally, the application token identifies the organization to query.

curl -sS -L -X GET "https://api.astra.datastax.com/v2/databases" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
Response

A successful request returns 200 Created and an array of objects containing information about each database in the organization.

This example response contains one database object, and it is truncated for brevity.

[
  {
    "id": "DB_ID",
    "orgId": "organizations/ORG_ID",
    "ownerId": "users/USER_ID",
    "info": {
      "name": "DB_NAME",
      "keyspace": "INITIAL_KEYSPACE_NAME",
      "cloudProvider": "CLOUD_PROVIDER",
      "region": "REGION",
      "additionalKeyspaces": [
        "SECOND_KEYSPACE_NAME"
      ],
      "dbType": "vector"
    },
    "creationTime": "2012-11-01T22:08:41+00:00",
    "terminationTime": "2019-11-01T22:08:41+00:00",
    "status": "ACTIVE",
    # Response truncated for brevity
  }
]

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": "C20",
    "status": "ACTIVE",
    "cloudProvider": "GCP",
    "region": "us-east1",
    "regionZone": "na",
    "regionClassification": "standard",
    "capacityUnits": 2,
    "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