Integrate CircleCI with Astra DB Serverless

query_builder 30 min

CircleCI is a continuous integration and continuous delivery (CI/CD) platform that integrates with code repositories and includes features like pipeline automation and monitoring.

Your CircleCI workflows can connect to your Astra DB Serverless databases and issue DevOps API, Data API, and Astra CLI commands.

Prerequisites

  • Familiarity with the concepts of CI/CD, unit testing, and integration testing.

    Familiarity with CircleCI is recommended.

  • A CircleCI account.

  • A code repository, such as a GitHub repository.

  • One or more Astra DB Serverless databases exclusively for testing that are loaded with test data.

    For more information, see the following section about preparing test databases.

Prepare test databases

Because Astra is a cloud-based DBaaS offering, if you want to perform unit and integration tests with Astra’s full set of features and APIs, DataStax recommends that you create dedicated test databases in Astra.

You can create separate databases for each developer or team, depending on your testing requirements. With separate databases, your developers are less likely to hit the per-database collection limit, they can keep test data separated, and they can test in relative or absolute isolation. For further separation, you can create separate Astra organizations for each team or environment (development, test, production).

Long-lived test databases are recommended for faster testing and minimal access requirements.

If you choose to terminate the test database after each workflow run, you must recreate and repopulate it for each workflow run. This increases the workflow’s runtime and complexity. For example, your scripts must wait long enough for the database to be created before attempting to write to the test data. Additionally, creating databases requires more expansive credentials than reading and writing to existing databases.

For more information about integrating Astra into your DevOps pipelines, contact your DataStax account representative or DataStax Support.

Set up your CircleCI project

  1. In CircleCI, go to Projects, and then connect a new repository or find an existing repository where you want to run a CircleCI workflow.

  2. Click Set Up Project.

  3. Select the option to use a config.yml template.

  4. Select the project’s language or dependency manager to help create the template.

    For example, if your project uses spring-boot-starter-data-cassandra, you would select a Java option. Similarly, if your project uses the Data API Python client, you would choose a Python option.

  5. Populate the config.yml for your project.

    The following example is based on a project that uses spring-boot-starter-data-cassandra, and only uses a mvn test command to test the database connection.

    For more information about building a config.yml, see the CircleCI configuration reference.

    config.yml
    # version of CircleCI pipeline process engine.
    version: 2.1
    
    # Define jobs
    jobs:
      build-and-test:
        docker:
          - image: cimg/openjdk:17.0.4
        steps:
          - checkout
          - run:
              name: Maven build
              command: mvn -B -DskipTests clean package
          - run:
              name: Test
              command: mvn test
    
    # Invoke jobs via workflows
    workflows:
      project-workflow:
        jobs:
          - build-and-test

Set Astra connection variables

Add environment variables to your CircleCI project to connect to your test database.

The following variables are for example purposes only. Your project might require different variables. For example, if you are using the Data API, you need variables that can connect the client to your database.

  • ASTRA_DB_ID: The ID of your test database.

  • ASTRA_DB_APP_TOKEN: An Astra application token with sufficient permissions to access your test database and execute the commands that you will include in your CircleCI workflow. For more information, see Manage application tokens.

  • ASTRA_DB_REGION: The name of a region where your test database is deployed. For multi-region databases, choose the region closest to you for lower latency.

  • ASTRA_DB_KEYSPACE: The name of a keyspace in your test database, such as default_keyspace.

For security reasons, CircleCI environment variables are masked and locked after you create them. If a variable is incorrect, you must delete and recreate it.

Run your pipeline

After setting up your project, config.yml, and environment variables, you can run your pipeline to test it. You can do this with the CircleCI in-app configuration editor, or use pipeline triggers.

See also

For more information about building CircleCI pipelines, see the CircleCI documentation.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax, an IBM Company | 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