Good News everyone, Spring Data Couchbase 2 was released last week and is now available on the awesome Spring Initializr. This awesome website let you start a Spring/Couchbase project very quickly. Just select the dependencies you want for your project, hit the Generate Project button and you’ll end up with an archive containing a project ready to be imported. This wizard is also available in the Spring Tool Suite.

1/ Go to

2/ Right now it’s only available with Spring Boot 1.4.0-SNAPSHOT so make sure you start by selecting the right SpringBoot version.

3/ Select Couchbase

4/ Add any other dependencies you might require for your project

5/ Generate the project

Now you have an archive ready to be imported in your editor of choice. As I am doing Spring stuff I tend to stick with their default tool suite. It’s basically Eclipse pre-configured with the right set of plugins.

6/ I have stuck with Maven in the generation wizard so I can simply import it as an existing maven project.

To activate the default config, you need to add the following in your file:

Or you can create a @Configuration Bean that extends AbstractCouchbaseConfiguration. Now we’re ready to start. Here’s a quick inventory of what the Spring Boot Couchbase auto-config gives you.


You can define several properties to configure your access to Couchbase, here are the defaults:

  • read-your-own-writes is stale=false and ScanConsistency=statement_plus
  • strongly-consistent is stale=false and ScanConsistency=request_plus
  • update-after is stale=update-after and ScanConsistency=not_bounded
  • eventually-consistent is stale=true and ScanConsistency=not_bounded

Stale Level

If stale=true is set, Couchbase will not refresh the view even if it is stale. The benefit of this is an improved query latency. If stale=update_after is set, Couchbase will update the view after the stale result is returned. If stale=false is set, Couchbase will refresh the view and return you most updated results.

Scan Consistency Level


This is the default (for single-statement requests). No timestamp vector is used in the index scan. This is also the fastest mode, because we avoid the cost of obtaining the vector, and we also avoid any wait for the index to catch up to the vector.


This implements strong consistency per request. Before processing the request, a current vector is obtained. The vector is used as a lower bound for the statements in the request. If there are DML statements in the request, RYOW is also applied within the request.


This implements strong consistency per statement. Before processing each statement, a current vector is obtained and used as a lower bound for that statement.

Index annotation

Here’s an example of repository with automatic index creation. When the repository bean is initialized, we make sure the index defined by the annotations exist and if not create them.

Index should be used for development only. We advise turning automatic index generation off in production and make sure you create the right index in the right nodes during your deployment process.


This annotation lets you define the name of the design document and View name as well as a custom map and reduce function.


This annotation makes sure that the bucket associated to the current repository will have a N1QL primary index.


This annotation makes sure that a secondary index exists on the type of your Entity.

Available Beans

If you have enabled the auto-config, you will have access to several Beans, here’s a list of the most useful ones:

  • CouchbaseTemplate couchbaseTemplate
    • Gives you access to the low-level Spring Data Couchbase API
  • ValidatingCouchbaseEventListener validationEventListener
    • javax.validation dependant entities validator. When it is registered as Spring component its automatically invoked before entities are saved in database.
  • CustomConversions customConversions
    • Used to capture custom JSON type conversions.
  • Bucket couchbaseClient
    • Direct access to the configured Bucket


This should have given you a good overview of what is available when starting a new project with spring-boot-starter-data-couchbase. For more details about Spring Data Couchbase 2, please refer to the documentation or checkout this blog regularly for more Spring/Couchbase goodness.


Posted by Laurent Doguin, Developer Advocate, Couchbase

Laurent is a Paris based Developer Advocate where he focuses on helping Java developers and the French community. He writes code in Java and blog posts in Markdown. Prior to joining Couchbase he was Nuxeo’s community liaison where he devoted his time and expertise to helping the entire Nuxeo Community become more active and efficient.

Leave a reply