Cloudant NoSQL DB is a non-relational, distributed database based on the Apache CouchDB project and the open source BigCouch project.
This guide will show you how to use the Cloudant Spring Boot Starter to access a Cloudant DB service from a Spring Boot application. This example uses a Cloudant DB on IBM Cloud. You will perform the following steps:
- Create a Spring Boot application using the Spring Initializr
- Create a Cloudant DB service on IBM Cloud
- Add the Cloudant DB service config (credentials and URL) to your application
- Add the Cloudant Spring Boot Starter
- Add a REST endpoint that accesses the Cloudant DB and returns the results
- Build the app and invoke the REST endpoint and display the Cloudant DB results
- Maven and Java installed on your computer. It is assumed that you can build and run a Maven based Spring Initializr project.
- An IBM Cloud account – sign up for free if you don’t have an account yet
Create a Spring Boot application with the Spring Initializr
On the Spring Initializr page generate a
Maven Project with language
Java, and the
Web dependency. For this example we use group
com.example and artifact
cloudant-spring. Download the project and unzip it.
Create a Cloudant service using the IBM Cloud Catalog
On the IBM Cloud Data & Analytics Catalog select the Cloudant NoSQL DB service. The Lite version of the service is available to try for free.
Add databases to the Cloudant service
The Cloudant service can contain multiple databases, but initially has none.
To add databases select the Cloudant service on your IBM Cloud Dashboard and click on “Launch” to display the Cloudant Dashboard. On the dashboard select the “Databases” tab on the left and use the “Create Database” button on the top to add two databases.
Add the service URL and credentials to the app
Select the Cloudant service on your IBM Cloud Dashboard and then select “Service credentials” in the left pane. If no credentials are listed, click the “New credential” button to create a set of credentials. Then click on “View credentials” to display the service credentials.
Edit the unzipped Spring Initializr project and add the credentials to the
src/main/resources/application.properties file with the following property names:
cloudant.url=<your-cloudant-url> cloudant.username=<your-cloudant-username> cloudant.password=<your-cloudant-password>
Note: It is not recommended to store credentials in your application. We do so here only for the sake of simplicity in this tutorial. The Cloudant Spring Boot Starter can utilize other property sources such as environment variables, etc.
Add the Cloudant Spring Boot Starter, and a REST endpoint to access the Cloudant service
For this example we’ll create a simple REST application with an endpoint that queries the Cloudant service and returns a list of the database names created in the previous step.
Edit the unzipped Spring Boot project to make the following changes:
Add the following dependency in the
<dependency> <groupId>com.cloudant</groupId> <artifactId>cloudant-spring-boot-starter</artifactId> <version>0.0.3</version> </dependency>
For the REST endpoint add a
@RestControllerannotation to the Spring Boot application class that was created by the Spring Initializr –
com/example/cloudantspring/CloudantSpringApplication.java. (Note that the Java package and class names are derived from the Group and Artifact values entered on the Initializr).
- Add an
@Autowiredannotation for the
CloudantClientobject. The Cloudant Spring Boot Starter will create the
CloudantClientobject with the credentials found in
- Now add a REST endpoint with the
@GetMappingannotation. Use the
CloudantClient getAllDbs()method to get the names of all the DB’s in the Cloudant service, and then return a message containing the names.
Your Spring Boot application should now look like the code below (shown here in the Intellij Idea IDE).
Build and run the app, and invoke the Cloudant DB service
Build and run your app with the following command:
mvn package spring-boot:run
Now you can invoke the REST endpoint –
http://localhost:8080/cloudant. You should see the message from your REST endpoint listing the DB’s in your Cloudant service:
The Cloudant Spring Boot Starter makes it easy to configure and use a Cloudant NoSQL DB in a Spring native fashion using Spring auto configuration and Spring Boot properties.