Cloudant/CouchDB Spring Boot Starter
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Cloudant/CouchDB Auto-Configuration for Spring Boot

Build Status Coverage Status Maven Central

A convienient way to use the official Cloudant client with Spring Boot.

Compatible with SpringBoot 2.





repositories {
dependencies {

Previous version

Use spring-boot-1.x branch for the build tested for previous version - 0.9.5.


Inject a database:

public Database mydb(CloudantClient cloudant) {
	return cloudant.database("mydb", true);

Then start using it:

Database mydb;;

Using the Cloudant client directly

Alternatively, you may inject the client for fine-grain controls:

CloudantClient cloudant
Database db = cloudant.database("mydb", true);


Spring Boot Configuration

Configurations can be placed in the (or yml) as usual. Either username/password or a URL must be specified.

##### Mandatory: Provide URL or username/password  #####
cloudant.username=myUserName              #Username as assigned by Cloudant.
cloudant.password=myPasswd                #Password as assigned by Cloudant.
cloudant.url=http...                      #Url to CouchDB or a Cloudant instance. Defaults to official Cloudant server.

##### Optional configs #####
cloudant.account=myAccountName            #Defaults to username if left blank.
cloudant.proxyURL=http...                 #URL to proxy server.
cloudant.proxyUser=myUserName             #Proxy username.
cloudant.proxyPassword=myPasswd           #Proxy password.
cloudant.connectTimeout=300               #Connect timeout in seconds. Default to 300 sec (5 minutes).
cloudant.readTimeout=300                  #Read timeout in seconds. Default to 300 sec (5 minutes).
cloudant.maxConnections=6                 #Default to 6.
cloudant.disableSSLAuthentication=false   #Defaults to false.

Bluemix (CloudFoundry) Configuration

When using Bluemix (CloudFoundry), the client will automatically use the Cloudant service binded to the app instead of the Spring configuration.

Bluemix's VCAP_SERVICES environment variable containing a Cloudant service will always take precedence over any Spring configuration. This is useful - Local development will use the Spring configuration properties, and promoting it to Bluemix will automatically use the environment configured instance. If Spring's configuration is desired, just remove the Cloudant service binding from your Bluemix app.

CouchDB Compatibility

Since Cloudant API is compatible with Apache CouchDB's API, this client can be used with a regular CouchDB instance. This is useful for things like local development or if you want to host your own service.

To connect to CouchDB on localhost for example, just set the url:



Example app is available at



Version 2.0 of the Apache License.