Convert-Cassandra-To-Spring-Data-Cosmos

# Comprehensive Guide: Converting Spring Boot Cassandra Applications to use Azure Cosmos DB with Spring Data Cosmos (spring-data-cosmos)

Applicability

This guide applies to:

- ✅ Spring Boot 2.x - 3.x applications (both reactive and non-reactive)

- ✅ Maven and Gradle-based projects

- ✅ Applications using Spring Data Cassandra, Cassandra DAOs, or DataStax drivers

- ✅ Projects with or without Lombok

- ✅ UUID-based or String-based entity identifiers

- ✅ Both synchronous and reactive (Spring WebFlux) applications

This guide does NOT cover:

- ❌ Non-Spring frameworks (Jakarta EE, Micronaut, Quarkus, plain Java)

- ❌ Complex Cassandra features (materialized views, UDTs, counters, custom types)

- ❌ Bulk data migration (code conversion only - data must be migrated separately)

- ❌ Cassandra-specific features like lightweight transactions (LWT) or batch operations across partitions

Overview

This guide provides step-by-step instructions for converting reactive Spring Boot applications from Apache Cassandra to Azure Cosmos DB using Spring Data Cosmos. It covers all major issues encountered and their solutions, based on real-world conversion experience.

Prerequisites

- Java 11 or higher (Java 17+ required for Spring Boot 3.x)

- Azure CLI installed and authenticated (`az login`) for local development

- Azure Cosmos DB account created in Azure Portal

- Maven 3.6+ or Gradle 6+ (depending on your project)

- For Gradle projects with Spring Boot 3.x: Ensure JAVA_HOME environment variable points to Java 17+

- Basic understanding of your application's data model and query patterns

Database Setup for Azure Cosmos DB

**CRITICAL**: Before running your application, ensure the database exists in your Cosmos DB account.

Option 1: Manual Database Creation (Recommended for first run)

1. Go to Azure Portal → Your Cosmos DB account

2. Navigate to "Data Explorer"

3. Click "New Database"

4. Enter the database name matching your application configuration (check `application.properties` or `application.yml` for the configured database name)

5. Choose throughput settings (Manual or Autoscale based on your needs)

- Start with Manual 400 RU/s for development/testing

- Use Autoscale for production workloads with variable traffic

6. Click OK

Option 2: Automatic Creation

Spring Data Cosmos can auto-create the database on first connection, but this requires:

- Proper RBAC permissions (Cosmos DB Built-in Data Contributor role)

- May fail if permissions are insufficient

Container (Collection) Creation

Containers will be auto-created by Spring Data Cosmos when the application starts, using the `@Container` annotation settings from your entities. No manual container creation is needed unless you want to configure specific throughput or indexing policies.

Authentication with Azure Cosmos DB

Using DefaultAzureCredential (Recommended)

The `DefaultAzureCredential` authentication method is the recommended approach for both development and production:

**How it works**:

1. Tries multiple credential sources in order:

- Environment variables

- Workload Identity (for AKS)

- Managed Identity (for Azure VMs/App Service)

- Azure CLI (`az login`)

- Azure PowerShell

- Azure Developer CLI

**Setup for local development**:

# Login via Azure CLI
az login

# The application will automatically use your CLI credentials

**Configuration** (no key required):

@Bean
public CosmosClientBuilder getCosmosClientBuilder() {
    return new CosmosClientBuilder()
        .endpoint(uri)
        .credential(new DefaultAzureCredentialBuilder().build());
}

**Properties file** (application-cosmos.properties or application.properties):

azure.cosmos.uri=https://<your-cosmos-account-name>.documents.azure.com:443/
azure.cosmos.database=<your-database-name>
# No key property needed when using DefaultAzureCredential
azure.cosmos.populate-query-metrics=false

**Note**: Replace `<your-cosmos-account-name>` an