Connect to a database

When you develop applications that interact with your Astra DB Serverless databases, you must connect to your databases programmatically.

Astra DB Serverless offers several methods to connect to your databases including APIs, CLI tools, and client libraries.

Depending on your use case, you might use one or more of these options.

Use case Requirements Recommended methods

Application development

Use a Serverless (Vector) database

Data API and clients

Use a Serverless (Non-Vector) database

CQL and Drivers

Use specific CQL functions that aren’t supported by the Data API

CQL and Drivers

Maintain a legacy application that relies on a driver or CQL

CQL and Drivers

Administration

Perform administrative tasks programmatically

Other

Streaming

Migration and bulk loading

Third-party integrations

Varies by provider and use case; see Integrations overview

Programmatic authentication is handled through either application tokens or Secure Connect Bundles.

APIs

Use the Data API and DevOps API to programmatically interact with your Astra DB organizations and databases.

DevOps API

Use the DevOps API for administration and high-level database management tasks, such as database creation, user management, and security configurations.

For more information, see Get started with the Astra DevOps API.

Data API

Use the Data API to work with Serverless (Vector) databases, including commands for creating collections and tables, loading data, querying data, and more.

You can access the Data API over HTTP or through the Data API clients.

If you’re new to the Data API, try the quickstart for collections or the quickstart for tables for a demo of some common operations.

For detailed Data API and client reference material, see Get started with the Data API.

Legacy Stargate APIs (deprecated)

The legacy APIs are deprecated for Astra DB Serverless as of September 2024, and end-of-life (EOL) is scheduled for the end of 2025. As EOL approaches, you can do either of the following:

  • Migrate your data to a new Serverless (Vector) database, and then use the Data API.

  • Keep your data in your Serverless (Non-Vector) database, and then use CQL and Astra DB-compatible drivers.

If you have questions or concerns, contact your account representative or DataStax Support.

Legacy Stargate APIs include the following:

  • Document API: If you use this API, DataStax recommends that you use the vector-enabled Data API.

  • REST API: Exposes CRUD access to data stored in Cassandra tables.

  • GraphQL API: Modifies and queries table data using GraphQL types, mutations, and queries with any Cassandra deployment.

  • gRPC API: A data gateway deployed between client applications and a database. The Stargate gRPC API is implemented to create language-specific queries using CQL with any Cassandra deployment.

Table-based authentication and authorization for legacy APIs

Table-based authentication and authorization uses the Stargate Auth API to generate an auth token based on a Cassandra username and password. The auth-table-based-service uses the generated auth token to allow Stargate API queries access to the Cassandra data.

By default, the token persists for 30 minutes with a sliding window. Each use of the token to authenticate resets the 30 minute window. A token created and used after 29 minutes will authenticate a request, but if 31 minutes passes before use, the token will no longer exist.

You can use the REST API to generate an auth token:

curl -L -X POST "https://ASTRA_DB_ID-ASTRA_DB_REGION.apps.astra.datastax.com/api/rest/v1/auth" \
-H "Content-Type: application/json" \
--data-raw '{
  "username": "CLIENT_ID",
  "password": "CLIENT_SECRET"
}'

A successful response includes the authentication token:

{ "authToken": "AUTH_TOKEN" }

You must provide this token in each subsequent request in the X-Cassandra-Token header. You can provide the token directly in the header or export it as an environment variable.

  • REST or Document API (v2): Store the auth token in an environment variable to make it easy to use with HTTP:

    export AUTH_TOKEN=AUTH_TOKEN
  • GraphQL: Add the auth token to the HTTP Headers box in the GraphQL playground:

    { "X-Cassandra-Token": "AUTH_TOKEN" }

Clients

You can use the Data API clients to access all Data API commands and some DevOps API endpoints. You can also connect to the Astra DB APIs over HTTP.

Language Client Version Dependency Documentation

Python

astrapy

Latest astrapy release on GitHub

Python 3.9 or later

Get started with the Data API

TypeScript

astra-db-ts

Latest astra-db-ts release on GitHub

Node.js 18 or later

Get started with the Data API

Java

astra-db-java

Latest astra-db-java release on Maven Central

Java 17 or later (21 recommended)

Get started with the Data API

If you’re new to the Data API, try the quickstart for collections or the quickstart for tables for a demo of some common operations.

For detailed Data API and client reference material, see Get started with the Data API.

Drivers

You can use drivers to interact with your Astra DB databases, including sending Cassandra Query Language (CQL) statements.

DataStax recommends Data API clients for most applications. Use drivers for Serverless (Non-Vector) databases, legacy applications that rely on a driver, and use cases that require specific CQL functions that aren’t supported by the Data API.

The following drivers are compatible with Astra DB:

Language Driver Version Documentation

C++

cpp-driver

Latest cpp-driver release on GitHub

Connect with the C++ driver

C#

csharp-driver

Latest csharp-driver release on GitHub

Connect with the C# driver

Go

gocql-astra (with cassandra-gocql-driver)

Latest gocql release on GitHub

Connect with the Go driver

Java

cassandra-java-driver

Latest cassandra-java-driver release on GitHub

Connect with the Java driver

Node.js

nodejs-driver

Latest nodejs-driver release on GitHub

Connect with the Node.js driver

Python

python-driver

Latest python-driver release on GitHub

Connect with the Python driver

Scala

spark-cassandra-connector

Latest spark-cassandra-connector release on GitHub

Connect to Astra DB Serverless with the Apache Spark Cassandra connector

If you want to use a CQL driver that isn’t compatible with Astra DB, consider using cql-proxy. This utility provides connectivity for incompatible drivers by securely forwarding your application’s CQL traffic to an appropriate database service.

cql-proxy isn’t required for supported driver versions, which are already compatible with Astra DB Serverless.

CQL shell

Because Astra DB Serverless is powered by Apache Cassandra®, you can use Cassandra Query Language (CQL) to programmatically interact with your databases through the CQL shell (cqlsh) or a driver. For more information, see CQL for Astra DB.

DataStax Bulk Loader

The DataStax Bulk Loader (DSBulk) supports large data uploads and migrations. For more information, see the DataStax Bulk Loader reference.

Astra CLI

The Astra DB Command-Line Interface (Astra CLI) provides commands you can use to create and manage Astra DB and Astra Streaming resources.

For example:

For more information and commands, see the Astra CLI documentation

You can use Astra CLI in addition to other connection methods.

Astra Portal

The Astra Portal provides a web-based interface to manage your Astra DB organizations and databases. It is best for administrative tasks and high-level database management, including inspecting database health metrics.

For application development, fine-grained data manipulation, and nuanced searches, you must use a programmatic approach.

For information about accessing the Astra Portal, see Manage your Astra account and Firewall rules for the Astra Portal.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax | Privacy policy | Terms of use | Manage Privacy Choices

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