How to use the Spring Boot Starter with the Azure Cosmos DB SQL API

Azure Cosmos DB is a globally distributed database service that allows developers to work with data using various standard APIs, such as SQL, MongoDB, Graph, and Table APIs. Microsoft's Spring Boot Starter enables developers to use Spring Boot applications that easily integrate with Azure Cosmos DB by using the SQL API.

This article demonstrates creating an Azure Cosmos DB using the Azure portal, then using the Spring Initializr to create a custom Spring Boot application, and then add the Azure Spring Boot Starter for Azure Cosmos DB to your custom application to store data in and retrieve data from your Azure Cosmos DB by using Spring Data and the Cosmos DB SQL API.

Prerequisites

Create an Azure Cosmos DB by using the Azure portal

  1. Browse to the Azure portal at https://portal.azure.com/ and select Create a resource.

  2. Select Databases, and then select Azure Cosmos DB.

    Selecting Azure Cosmos DB in the Azure portal.

  3. On the Azure Cosmos DB page, enter the following information:

    • Choose the Subscription you want to use for your database.
    • Specify whether to create a new Resource group for your database, or choose an existing resource group.
    • Enter a unique Account Name, which you will use as the URI for your database. For example: contosoaccount.
    • Choose Core (SQL) for the API.
    • Specify the Location for your database.

    When you have specified these options, select Review + create, review your specifications, and select Create.

    Select Review + Create to proceed.

  4. When your database has been created, it is listed on your Azure Dashboard, and under the All Resources and Azure Cosmos DB pages. You can select your database for any of those locations to open the properties page for your cache.

  5. When the properties page for your database is displayed, select Keys and copy your URI and access keys for your database; you will use these values in your Spring Boot application.

    Copy the URI and access keys in the Keys section.

Create a Spring Boot application with the Spring Initializr

Use the following steps to create a new Spring Boot application project with Azure support. As an alternative, you can use the azure-spring-boot-sample-cosmosdb sample in the azure-sdk-for-java repo. Then, you can skip directly to Build and test your app.

  1. Browse to https://start.spring.io/.

  2. Specify the following options:

    • Generate a Maven project with Java.
    • Specify your Spring Boot version.
    • Specify the Group and Artifact names for your application.
    • Select 11 for the Java version.
    • Add Azure Support in the dependencies.

    Basic Spring Initializr options

    Note

    1. The Spring Initializr uses the Group and Artifact names to create the package name; for example: com.example.wingtiptoysdata.
    2. The version of Spring Boot may be higher than the version supported by Azure Support. After the project is automatically generated, you can manually change the Spring Boot version to the highest version supported by Azure, which you can find here.
  3. When you have specified the options listed above, select GENERATE.

  4. When prompted, download the project to a path on your local computer and extract the files.

Your simple Spring Boot application is now ready for editing.

Configure your Spring Boot application to use the Azure Spring Boot Starter

  1. Locate the pom.xml file in the directory of your app; for example:

    C:\SpringBoot\wingtiptoysdata\pom.xml

    -or-

    /users/example/home/wingtiptoysdata/pom.xml

  2. Open the pom.xml file in a text editor, and add the following to the <dependencies> element:

    <dependency>
        <groupId>com.azure.spring</groupId>
        <artifactId>azure-spring-boot-starter-cosmos</artifactId>
        <version>3.0.0</version>
    </dependency>
    
  3. Verify that the properties element indicates the required versions of Java and Azure:

    <properties>
        <java.version>11</java.version>
        <azure.version>3.0.0</azure.version>
    </properties>
    
  4. Save and close the pom.xml file.

Configure your Spring Boot application to use your Azure Cosmos DB

  1. Locate the application.properties file in the resources directory of your app; for example:

    C:\SpringBoot\wingtiptoysdata\src\main\resources\application.properties

    -or-

    /users/example/home/wingtiptoysdata/src/main/resources/application.properties

  2. Open the application.properties file in a text editor, and add the following lines to the file, and replace the sample values with the appropriate properties for your database:

    # Specify the DNS URI of your Azure Cosmos DB.
    azure.cosmos.uri=https://contosoaccount.documents.azure.com:443/
    
    # Specify the access key for your database.
    azure.cosmos.key=replace-your-access-key-here
    
    # Specify the name of your database. 
    azure.cosmos.database=contosoaccount
    azure.cosmos.populateQueryMetrics=true
    
  3. Save and close the application.properties file.

Add sample code to implement basic database functionality

In this section you create two Java classes for storing user data, and then you modify your main application class to create an instance of the User class and save it to your database.

Define a base class for storing user data

  1. Create a new file named User.java in the same directory as your main application Java file.

  2. Open the User.java file in a text editor, and add the following lines to the file to define a generic user class that stores and retrieve values in your database:

    package com.example.wingtiptoysdata;
    
    import com.azure.spring.data.cosmos.core.mapping.Container;
    import com.azure.spring.data.cosmos.core.mapping.PartitionKey;
    import org.springframework.data.annotation.Id;
    
    @Container(containerName = "mycollection")
    public class User {
        @Id
        private String id;
        private String firstName;
        @PartitionKey
        private String lastName;
        private String address;
    
        public User() {
    
        }
    
        public User(String id, String firstName, String lastName, String address) {
            this.id = id;
            this.firstName = firstName;
            this.lastName = lastName;
            this.address = address;
        }
    
        public String getId() {
            return id;
        }
    
        public void setId(String id) {
            this.id = id;
        }
    
        public String getFirstName() {
            return firstName;
        }
    
        public void setFirstName(String firstName) {
            this.firstName = firstName;
        }
    
        public String getLastName() {
            return lastName;
        }
    
        public void setLastName(String lastName) {
            this.lastName = lastName;
        }
    
        public String getAddress() {
            return address;
        }
    
        public void setAddress(String address) {
            this.address = address;
        }
    
        @Override
        public String toString() {
            return String.format("%s %s, %s", firstName, lastName, address);
        }
    }
    
  3. Save and close the User.java file.

Define a data repository interface

  1. Create a new file named UserRepository.java in the same directory as your main application Java file.

  2. Open the UserRepository.java file in a text editor, and add the following lines to the file to define a user repository interface that extends the default ReactiveCosmosRepository interface:

    package com.example.wingtiptoysdata;
    
    import com.azure.spring.data.cosmos.repository.ReactiveCosmosRepository;
    import org.springframework.stereotype.Repository;
    import reactor.core.publisher.Flux;
    
    @Repository
    public interface UserRepository extends ReactiveCosmosRepository<User, String> {
        Flux<User> findByFirstName(String firstName);
    }
    

    The ReactiveCosmosRepository interface replaces the DocumentDbRepository interface from the previous version of the starter. The new interface provides synchronous and reactive APIs for basic save, delete, and find operations.

  3. Save and close the UserRepository.java file.

Modify the main application class

  1. Locate the main application Java file in the package directory of your application, for example:

    C:\SpringBoot\wingtiptoysdata\src\main\java\com\example\wingtiptoysdata\WingtiptoysdataApplication.java

    -or-

    /users/example/home/wingtiptoysdata/src/main/java/com/example/wingtiptoysdata/WingtiptoysdataApplication.java

  2. Open the main application Java file in a text editor, and add the following lines to the file:

    package com.example.wingtiptoysdata;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.boot.CommandLineRunner;
    import org.springframework.util.Assert;
    import reactor.core.publisher.Flux;
    import reactor.core.publisher.Mono;
    
    import java.util.Optional;
    
    @SpringBootApplication
    public class WingtiptoysdataApplication implements CommandLineRunner {
    
        private static final Logger LOGGER = LoggerFactory.getLogger(WingtiptoysdataApplication.class);
    
        @Autowired
        private UserRepository repository;
    
        public static void main(String[] args) {
            SpringApplication.run(WingtiptoysdataApplication.class, args);
        }
    
        public void run(String... var1) {
            this.repository.deleteAll().block();
            LOGGER.info("Deleted all data in container.");
    
            final User testUser = new User("testId", "testFirstName", "testLastName", "test address line one");
    
            // Save the User class to Azure Cosmos DB database.
            final Mono<User> saveUserMono = repository.save(testUser);
    
            final Flux<User> firstNameUserFlux = repository.findByFirstName("testFirstName");
    
            //  Nothing happens until we subscribe to these Monos.
            //  findById will not return the user as user is not present.
            final Mono<User> findByIdMono = repository.findById(testUser.getId());
            final User findByIdUser = findByIdMono.block();
            Assert.isNull(findByIdUser, "User must be null");
    
            final User savedUser = saveUserMono.block();
            Assert.state(savedUser != null, "Saved user must not be null");
            Assert.state(savedUser.getFirstName().equals(testUser.getFirstName()), "Saved user first name doesn't match");
    
            firstNameUserFlux.collectList().block();
    
            final Optional<User> optionalUserResult = repository.findById(testUser.getId()).blockOptional();
            Assert.isTrue(optionalUserResult.isPresent(), "Cannot find user.");
    
            final User result = optionalUserResult.get();
            Assert.state(result.getFirstName().equals(testUser.getFirstName()), "query result firstName doesn't match!");
            Assert.state(result.getLastName().equals(testUser.getLastName()), "query result lastName doesn't match!");
    
            LOGGER.info("findOne in User collection get result: {}", result.toString());
        }
    }
    
  3. Save and close the main application Java file.

Build and test your app

  1. Open a command prompt and navigate to the folder where your pom.xml file is located; for example:

    cd C:\SpringBoot\wingtiptoysdata

    -or-

    cd /users/example/home/wingtiptoysdata

  2. Use the following command to build and run your application:

    mvnw clean
    

    This command runs the application automatically as part of the test phase. You can also use:

    mvnw spring-boot:run
    

    After some build and test output, your console window will display a message similar to the following:

    INFO 1365 --- [           main] c.e.w.WingtiptoysdataApplication         : Deleted all data in container.
    
    ... (omitting connection and diagnostics output) ...
    
    INFO 1365 --- [           main] c.e.w.WingtiptoysdataApplication         : findOne in User collection get result: testFirstName testLastName, test address line one
    

    The above output messages indicate that the data was successfully saved to Cosmos DB and then retrieved again.

Clean up resources

If you're not going to continue to use this application, be sure to delete the resource group containing the Cosmos DB you created earlier. You can do this from the Azure portal.

Next steps

To learn more about Spring and Azure, continue to the Spring on Azure documentation center.

More Resources

For more information about using Azure Cosmos DB and Java, see the following articles:

For more information about using Spring Boot applications on Azure, see the following articles:

For more information about using Azure with Java, see the Azure for Java Developers and the Working with Azure DevOps and Java.

The Spring Framework is an open-source solution that helps Java developers create enterprise-level applications. One of the more-popular projects that is built on top of that platform is Spring Boot, which provides a simplified approach for creating stand-alone Java applications. To help developers get started with Spring Boot, several sample Spring Boot packages are available at https://github.com/spring-guides/. In addition to choosing from the list of basic Spring Boot projects, the Spring Initializr helps developers get started with creating custom Spring Boot applications.