Create a database

Creates a database.

To replicate a database to additional datacenters, see Deploy an Astra DB Serverless database to multiple regions.

You need an application token with permission to create and configure databases, such as the Organization Administrator role.

For more information, see Get endpoint and token.

Result

Creates a database and returns an AstraDBDatabaseAdmin object that can perform administrative actions on the newly-created database.

Creates a database and returns a promise that resolves to an AstraDbAdmin object that can perform administrative actions on the newly-created database.

The Go client is in preview. For more information, see astra-db-go.

Creates a database and returns a AstraDatabaseAdmin struct that can perform administrative actions on the newly-created database.

Creates a database and returns a DatabaseAdmin object that can perform administrative actions on the newly-created database.

Creates a database and returns a DatabaseAdminAstra object that can perform administrative actions on the newly-created database.

Creates a database and returns 201 Created and the database ID.

It takes several minutes for the database to initialize and reach ACTIVE status.

Parameters

Use the create_database method, which belongs to the AstraDBAdmin class.

Method signature

create_database(
  name: str,
  *,
  definition: DatabaseDefinition,
  wait_until_active: bool,
  database_admin_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
  token: str | TokenProvider,
  spawn_api_options: APIOptions,
) -> AstraDBDatabaseAdmin

create_database(
  name: str,
  *,
  cloud_provider: str,
  region: str,
  keyspace: str,
  wait_until_active: bool,
  database_admin_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
  token: str | TokenProvider,
  spawn_api_options: APIOptions,
) -> AstraDBDatabaseAdmin

Name Type Summary

Name	Type	Summary
`name`	`str`	The name for 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
`definition`	`DatabaseDefinition`	The configuration for the database. If specified, you cannot separately specify `cloud_provider`, `region`, or `keyspace`. See Attributes of `DatabaseDefinition` for more details.
`cloud_provider`	`str`	Required unless you specify `definition`. You can’t specify both `cloud_provider` and `definition`. The cloud provider that should host the database. Can be one of: `aws`, `gcp`, `azure`.
`region`	`str`	Required unless you specify `definition`. You can’t specify both `region` and `definition`. The cloud provider region in which to create the database. The available regions depend on your Astra plan and the database type. To find available regions, see Find available regions.
`keyspace`	`str`	Optional. You can’t specify both `keyspace` and `definition`. The name for the database’s initial keyspace. Default: default_keyspace
`wait_until_active`	`bool`	Optional. Whether to wait for the database to become active before returning. If false, the method returns immediately after issuing the creation request, but you cannot work with the database until it becomes active. Default: true
`database_admin_timeout_ms`	`int`	Optional. A timeout, in milliseconds, to impose on the underlying API request. If not provided, the `AstraDBAdmin` defaults apply. This parameter is aliased as `request_timeout_ms` and `timeout_ms` for convenience.
`token`	`str` \| `TokenProvider`	Optional. The token used by the resulting `AstraDBDatabaseAdmin` object. The token should have sufficient permissions to perform the desired downstream operations. Default: The token used by the `AstraDBAdmin` object that called this method.
`spawn_api_options`	`APIOptions`	Optional. A complete or partial specification of the `APIOptions` to override the defaults inherited from the `AstraDBAdmin`. Use this to customize the interaction of the Python client with the database admin. For example, you can change the default timeouts. If `APIOptions` is passed together with a named parameter such as a timeout, the latter takes precedence over the corresponding `spawn_api_options` setting.

name

str

The name for 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

definition

DatabaseDefinition

The configuration for the database.

If specified, you cannot separately specify cloud_provider, region, or keyspace.

See Attributes of DatabaseDefinition for more details.

cloud_provider

str

Required unless you specify definition. You can’t specify both cloud_provider and definition.

The cloud provider that should host the database. Can be one of: aws, gcp, azure.

region

str

Required unless you specify definition. You can’t specify both region and definition.

The cloud provider region in which to create the database.

The available regions depend on your Astra plan and the database type. To find available regions, see Find available regions.

keyspace

str

Optional. You can’t specify both keyspace and definition.

The name for the database’s initial keyspace.

Default: default_keyspace

wait_until_active

bool

Optional. Whether to wait for the database to become active before returning. If false, the method returns immediately after issuing the creation request, but you cannot work with the database until it becomes active.

Default: true

database_admin_timeout_ms

int

Optional. A timeout, in milliseconds, to impose on the underlying API request. If not provided, the AstraDBAdmin defaults apply.

This parameter is aliased as request_timeout_ms and timeout_ms for convenience.

token

str | TokenProvider

Optional. The token used by the resulting AstraDBDatabaseAdmin object. The token should have sufficient permissions to perform the desired downstream operations.

Default: The token used by the AstraDBAdmin object that called this method.

spawn_api_options

APIOptions

Optional. A complete or partial specification of the APIOptions to override the defaults inherited from the AstraDBAdmin. Use this to customize the interaction of the Python client with the database admin. For example, you can change the default timeouts.

If APIOptions is passed together with a named parameter such as a timeout, the latter takes precedence over the corresponding spawn_api_options setting.

Name Type Summary

cloud_provider

str

The cloud provider that should host the database. Can be one of: aws, gcp, azure.

region

str

The cloud provider region in which to create the database.

The available regions depend on your Astra plan and the database type. To find available regions, see Find available regions.

keyspace

str

Optional. The name for the database’s initial keyspace.

Default: default_keyspace

pcu_group_id

str

Optional. The ID of the PCU group to use for provisioning the database. The specified PCU group must have the same cloud provider and region as the database. Only applicable for organizations that use PCU groups.

Default: No PCU group

db_type

str

Optional. Whether the database is a Serverless (vector) database or a Serverless (non-vector) database.

To create a Serverless (vector) database, set this parameter to vector.

To create a Serverless (non-vector) database, set it to nonvector.

The Data API is supported for Serverless (vector) and Serverless (non-vector) databases generally. However, vector and reranking functionalities aren’t compatible with all databases, tables, or collections.

Default: vector

tier

str

Optional. The database tier.

If specified, must be serverless.

Default: serverless

capacity_units

int

Optional. The number of capacity units for the database. This is unrelated to PCU group capacity.

If specified, must be 1.

Default: 1

Use the createDatabase method, which belongs to the AstraAdmin class.

Method signature

async createDatabase(
  config: {
    name: string,
    cloudProvider: AstraDatabaseCloudProvider,
    region: string,
    keyspace?: string,
    pcuGroupUUID?: string,
    tier?: string,
    capacityUnits?: number,
    dbType?: 'vector' | 'nonvector',
  },
  options: {
    blocking?: boolean,
    timeout?: number | TimeoutDescriptor,
    dbOptions?: DbOptions
  }
): AstraDbAdmin;

Name Type Summary

Name	Type	Summary
`config`	`object`	The database configuration. See Properties of `config` for more details.
`options`	`object`	Optional. The options for this operation. See Properties of `options` for more details.

config

object

The database configuration. See Properties of config for more details.

options

object

Optional. The options for this operation. See Properties of options for more details.

Name Type Summary

name

string

The name for 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

cloudProvider

AstraDatabaseCloudProvider

The cloud provider that should host the database. Can be one of: AWS, GCP, AZURE.

region

string

The cloud provider region in which to create the database.

The available regions depend on your Astra plan and the database type. To find available regions, see Find available regions.

keyspace

string

Optional. The name for the database’s initial keyspace.

Default: default_keyspace

pcuGroupUUID

string

Default: No PCU group

dbType

'vector' | 'nonvector'

Optional. Whether the database is a Serverless (vector) database or a Serverless (non-vector) database.

To create a Serverless (vector) database, set this parameter to vector.

To create a Serverless (non-vector) database, set it to nonvector.

Default: vector

tier

string

Optional. The database tier.

If specified, must be serverless.

Default: serverless

capacityUnits

number

Optional. The number of capacity units for the database. This is unrelated to PCU group capacity.

If specified, must be 1.

Default: 1

Properties of `options`
Name	Type	Summary
`blocking`	`boolean`	Optional. Whether to wait for the database to become active before returning. If false, the method returns immediately after issuing the creation request, but you cannot work with the database until it becomes active. Default: true
`timeout`	`number` \| `TimeoutDescriptor`	Optional. A timeout to impose on the underlying API request.
`options`	`DbOptions`	Optional. A specification of options to override the defaults inherited from the `AstraAdmin`. Use this to customize the interaction of the client with the database admin. For example, you can change the default timeouts or token.

The Go client is in preview. For more information, see astra-db-go.

Use the CreateDatabase method, which belongs to the AstraAdmin type.

Method signature

func (a *AstraAdmin) CreateDatabase(
  ctx context.Context,
  name string,
  params CreateDatabaseParams,
  opts ...options.CreateDatabaseOption
) (*AstraDatabaseAdmin, error)

Name Type Summary

Name	Type	Summary
`ctx`	`context.Context`	The context for the operation.
`name`	`string`	The name for 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
`params`	`CreateDatabaseParams`	The configuration for the database. See Fields of the `CreateDatabaseParams` struct for more details.
`opts`	`…options.DropDatabaseOption`	Optional. A builder to generate options for this operation. See Methods of the `DropDatabaseOption` builder for more details.

ctx

context.Context

The context for the operation.

name

string

The name for 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

params

CreateDatabaseParams

The configuration for the database.

See Fields of the CreateDatabaseParams struct for more details.

opts

…options.DropDatabaseOption

Optional. A builder to generate options for this operation. See Methods of the DropDatabaseOption builder for more details.

Name Type Summary

CloudProvider

options.CloudProvider

The cloud provider that should host the database.

Region

string

The cloud provider region in which to create the database.

The available regions depend on your Astra plan and the database type. To find available regions, see Find available regions.

PCUGroupUUID

string

Default: No PCU group

DbType

string

Optional. Whether the database is a Serverless (vector) database or a Serverless (non-vector) database.

To create a Serverless (vector) database, set this parameter to vector.

To create a Serverless (non-vector) database, set it to nonvector.

Default: vector

Tier

string

Optional. The database tier.

If specified, must be serverless.

Default: serverless

CapacityUnits

int

Optional. The number of capacity units for the database. This is unrelated to PCU group capacity.

If specified, must be 1.

Default: 1

Methods of the `DropDatabaseOption` builder
Method	Summary
`SetBlocking(v bool)`	Optional. Whether to wait for the database to become active before returning. If false, the method returns immediately after issuing the creation request, but you cannot work with the database until it becomes active. Default: true
`SetPollInterval(v time.Duration)`	Optional. Controls how often to check the database status if `SetBlocking()` is true. Default: 10 seconds
`SetKeyspace(v string)`	Optional. The name for the database’s initial keyspace. Default: default_keyspace
`UpdateAPIOptions(v …APIOption)`	Optional. General API options for this operation, including the timeout.

Use the createDatabase method, which belongs to the com.datastax.astra.client.admin.AstraDBAdmin class.

Method signature

DatabaseAdmin createDatabase(String name)

DatabaseAdmin createDatabase(
  String name,
  DatabaseDefinition definition,
  CreateDatabaseOptions options
)

DatabaseAdmin createDatabase(
  String name,
  DatabaseDefinition definition
)

DatabaseAdmin createDatabase(
  String name,
  CloudProviderType cloud,
  String cloudRegion
)

DatabaseAdmin createDatabase(
  String name,
  CloudProviderType cloud,
  String cloudRegion,
  boolean waitForDb
)

Name Type Summary

Name	Type	Summary
`name`	`String`	The name for 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
`definition`	`DatabaseDefinition`	The configuration for the database. See Methods of `DatabaseDefinition` for more details.
`options`	`CreateDatabaseOptions`	The configuration for the database. The options for this operation. See Methods of `CreateDatabaseOptions` for more details.
`cloud`	`CloudProviderType`	The cloud provider that should host the database. Default (if you only specify the database name): `gcp`
`cloudRegion`	`String`	The cloud provider region in which to create the database. The available regions depend on your Astra plan and the database type. To find available regions, see Find available regions. Default (if you only specify the database name): us-east1
`waitForDb`	`boolean`	Optional. Whether to wait for the database to become active before returning. If false, the method returns immediately after issuing the creation request, but you cannot work with the database until it becomes active. Default: true

name

String

The name for 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

definition

DatabaseDefinition

The configuration for the database.

See Methods of DatabaseDefinition for more details.

options

CreateDatabaseOptions

The configuration for the database.

The options for this operation. See Methods of CreateDatabaseOptions for more details.

cloud

CloudProviderType

The cloud provider that should host the database.

Default (if you only specify the database name): gcp

cloudRegion

String

The cloud provider region in which to create the database.

The available regions depend on your Astra plan and the database type. To find available regions, see Find available regions.

Default (if you only specify the database name): us-east1

waitForDb

boolean

Default: true

Method Parameters Summary

cloudProvider

CloudProviderType

The cloud provider that should host the database. Can be one of: aws, gcp, azure.

cloudRegion

String

The cloud provider region in which to create the database.

The available regions depend on your Astra plan and the database type. To find available regions, see Find available regions.

keyspace

String

Optional. The name for the database’s initial keyspace.

Default: default_keyspace

PCUGroupId

UUID

Default: No PCU group

dbType

String

Optional. Whether the database is a Serverless (vector) database or a Serverless (non-vector) database.

To create a Serverless (vector) database, set this parameter to vector.

To create a Serverless (non-vector) database, set it to nonvector.

Default: vector

tier

String

Optional. The database tier.

If specified, must be serverless.

Default: serverless

capacityUnits

Integer

Optional. The number of capacity units for the database. This is unrelated to PCU group capacity.

If specified, must be 1.

Default: 1

Methods of `CreateDatabaseOptions`
Method	Parameters	Summary
`waitForDb()`	`boolean`	Optional. Whether to wait for the database to become active before returning. If false, the method returns immediately after issuing the creation request, but you cannot work with the database until it becomes active. Default: true

Use the CreateDatabaseAsync method, which belongs to the AstraDatabasesAdmin class. You can also use CreateDatabase, which is the synchronous version of the method.

Method signature

public Task<DatabaseAdminAstra> CreateDatabaseAsync(
  CreateDatabaseOptions options
);

Name Type Summary

Name	Type	Summary
`options`	`CreateDatabaseOptions`	Optional. Options for this operation. For more information and examples for general options such as timeout, see Customize API interaction. See Method-specific properties of the `CreateDatabaseOptions` class for more details.

options

CreateDatabaseOptions

Optional. Options for this operation. For more information and examples for general options such as timeout, see Customize API interaction. See Method-specific properties of the CreateDatabaseOptions class for more details.

Name Type Summary

Name

string

The name of 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

CloudProvider

CloudProviderType

The cloud provider that should host the database. Can be one of: CloudProviderType.AWS, CloudProviderType.Azure, CloudProviderType.GCP

Region

string

The cloud provider region in which to create the database.

The available regions depend on your subscription plan and the database type. To find available regions, see Find available regions.

Keyspace

str

Optional. The name for the database’s initial keyspace.

Default: default_keyspace

PCUGroupId

string

Default: No PCU group

DBType

string

Optional. Whether the database is a Serverless (vector) database or a Serverless (non-vector) database.

To create a Serverless (vector) database, set this parameter to vector.

To create a Serverless (non-vector) database, set it to nonvector.

Default: vector

Tier

string

Optional. The database tier.

If specified, must be serverless.

Default: serverless

CapacityUnits

int

Optional. The number of capacity units for the database. This is unrelated to PCU group capacity.

If specified, must be 1.

Default: 1

waitForCompletion

bool

Default: true

Use the DevOps API to create a database.

The application token must have sufficient permissions to perform the requested operations, such as the Organization Administrator role.

Command signature

curl -sS -L -X POST "https://api.astra.datastax.com/v2/databases" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "name": "STRING",
  "keyspace": "STRING",
  "cloudProvider": "STRING",
  "region": "STRING",
  "dbType": "STRING",
  "tier": "serverless",
  "capacityUnits": INTEGER,
  "pcuGroupUUID": "STRING"
}'

Name Type Summary

name

string

The name for 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

string

Optional if dbType is vector. The name for the database’s initial keyspace.

Default if dbType is vector: default_keyspace

cloudProvider

string

The cloud provider that should host the database. Can be one of: aws, gcp, azure.

region

string

The cloud provider region in which to create the database.

The available regions depend on your Astra plan and the database type. To find available regions, see Find available regions.

dbType

string

Whether the database is a Serverless (vector) database or a Serverless (non-vector) database.

To create a Serverless (vector) database, set this parameter to vector.

To create a Serverless (non-vector) database, omit this parameter.

tier

string

The database tier. Must be serverless.

capacityUnits

integer

Must be 1. The number of capacity units for the database. This is unrelated to PCU group capacity.

pcuGroupUUID

string

Default: No PCU group

Examples

The following examples demonstrate how to create a database.

from astrapy import DataAPIClient
from astrapy.info import DatabaseDefinition

client = DataAPIClient("APPLICATION_TOKEN")

admin = client.get_admin()

admin.create_database(
   "DATABASE_NAME",
  definition=DatabaseDefinition(cloud_provider="gcp", region="us-east1")
)

import { DataAPIClient } from "@datastax/astra-db-ts";

const client = new DataAPIClient("APPLICATION_TOKEN");

const admin = client.admin();

(async function () {
  await admin.createDatabase({
    name: "DATABASE_NAME",
    cloudProvider: "GCP",
    region: "us-east1",
  });
})();

The Go client is in preview. For more information, see astra-db-go.

package main

import (
	"context"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
)

func main() {
	ctx := context.Background()

	client := astra.NewClient()

	admin, err := client.Admin()

	if err != nil {
		log.Fatal(err)
	}

	admin.CreateDatabase(
		ctx,
		"DATABASE_NAME",
		astra.CreateDatabaseParams{
			CloudProvider: "gcp",
			Region:        "us-east1",
		},
	)
}

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.admin.AstraDBAdmin;
import com.datastax.astra.client.admin.definition.DatabaseDefinition;
import com.dtsx.astra.sdk.db.domain.CloudProviderType;

public class Example {
  public static void main(String[] args) {
    DataAPIClient client = new DataAPIClient("APPLICATION_TOKEN");

    AstraDBAdmin admin = client.getAdmin();

    DatabaseDefinition definition =
        DatabaseDefinition.builder()
            .cloudProvider(CloudProviderType.GCP)
            .region("us-east-1")
            .build();

    admin.createDatabase("DATABASE_NAME", definition, null);
  }
}

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Admin;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    var client = new DataAPIClient("APPLICATION_TOKEN");

    var admin = client.GetAstraDatabasesAdmin();

    var databaseAdmin = await admin.CreateDatabaseAsync(
      new CreateDatabaseOptions()
      {
        Name = "DATABASE_NAME",
        CloudProvider = CloudProviderType.AWS,
        Region = "us-east-2",
      }
    );
  }
}

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": "gcp",
  "region": "us-east1",
  "dbType": "vector",
  "tier": "serverless",
  "capacityUnits": 1
}'

Client reference

For more information, see the client reference.

The Go client is in preview. For more information, see astra-db-go.

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Create a database

Result

Parameters

Examples

Client reference

Was this helpful?

Give Feedback