An Intro to Spring Data Couchbase

Right now I am trying to get an understanding of who is the Couchbase community, including how many people read these blos posts, follow us on our social network pages, ask questions on our forum, our mailing lists,etc. Of course, I need to store all this time-series data somewhere.

You guessed it: I’m going to be writing about storing time-based metrics in Couchbase. I will be using Java and Spring to do so, because there is a pretty cool project called spring-data-couchbase that is going to make things much easier for me. So, over three blog posts I’ll explain how I did it.

First a couple of word about Spring. From their own website:

The Spring Framework is a Java platform that provides comprehensive infrastructure support for developing Java applications. Spring handles the infrastructure so you can focus on your application.

You could say that its purpose is for you to write mostly business code and focus on what you want to do, than writing infrastructure code and focusing on how to do it. A good thing is that you don’t have to buy into the whole platform. Spring is made of many different modules. You can choose the one you want to use. Interaction between these modules and your code is mostly driven by Inversion of Control, also called Dependency Injection, more on that later.

If you are not familiar with Spring I really invite you to look at the Spring Projects page to get a quick overview of all the topics they address. Now let’s begin.

Boot-strapping dependencies

First up I need to bootstrap my project with the appropriate dependencies. Since I’m using Spring, I might as well just use Spring Boot to do so. It provides an opiniated way of building Spring applications, it assumes several choices and favor convention over configuration. That is perfect for the small project I am writing.

The first step to start a new Spring Boot project would be to go to It’s an assistant that lets you choose the dependencies you want to start your project with. The thing is, there is no possibility to choose spring-data-couchbase right now. So I ended up doing my own pom file. It’s very simple:

You can see that I am using the spring-boot-starter-social-facebook and spring-social-twitter projects. The Spring social projects are here to help you connect to SaaS API providers like Facebook, Twitter, Linkedin etc. The spring-boot-starter-* projects can be seen as a bootstrap POM that comes with the appropriate dependencies.

And if you would like a spring-boot-starter-data-couchbase entry on the site please speak up on our forum or by commenting this post.


I haven’t used Spring for a long while and I had it in my mind that all the configuration meant dealing with tedious XML files. I am happy to have discovered that things have changed and you can now declare configuration only with annotations. Yay!

Now that dependencies are all set, let’s write some code! Let’s start by creating an Application class extending the AbstractCouchbaseConfiguration class.

You can see that I implement three method, all needed to configure a Couchbase client connection to a bucket. They provide a list of URIs for the cluster nodes, the name and the password of the bucket.

To avoid hardcoding these values into the Java class, I’ve created an file under the resources folder. Its values are automatically picked up by Spring thanks to the @Value annotation. Pay attention to the ‘$’ sign used to retrieve values from a properties file. The ‘#’ sign would be used to evaluate traditional EL.

Make sure the @Configuration and @EnableAutoConfiguration annotations are present as they areneeded at runtime. The first one makes sure the beans you declared on this class will be picked by Spring. The second one gives you an automatically configured Application context to make sure you can run the SpringApplication.

A Word About IoC and Abstract Couchbase Configuration

One of the main paradigms available with Spring is IoC(Inversion of Control). It lets you inject objects. It means that instantiation of the object has been taken care of for you. The AbstractCouchbaseConfiguration class that we extend defines some Beans that can be injected anywhere in the application.

Now take a look at the commandLineRunner method. It’s annotated with @Bean and returns a CommandLineRunner instance (yes it’s an anonymous class but it uses Lambda expression, thank you Java8). It means that this CommandLineRunner will be picked up by the Spring Framework. Its code will be executed by the call in the main method. And because it’s a Spring Bean, IoC works right off and the CouchbaseClient bean will be injected automatically. You just have to pass it as a method parameter.

Making Sure it Works

Just to make sure the configuration works and that everything is ok, I will create a simple JSON object, store it in Couchbase, retrieve it from Couchbase and then log it.

It’s just those four lines of code you see in the CommandLineRunner. Now everything should work. If I go to the Couchbase web admin interface, I can see the document in the default bucket.

Now I know how to bootstrap a Spring project, configured a Couchbase connection and store objects in Couchbase. I am ready to use the spring social connectors and store my metrics. And that’s for the next blog post. Don’t hesitate to comment and share this one :)


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.


  1. Great post Laurent, thanks for sharing. It might be worth noting that there\’s ongoing efforts to add a dedicated Boot starter module to target Spring Data Couchbase. This would even simplify the setup in the pom.xml a bit and automatically default the application configuration, too.

    Speaking of the pom.xml – it contains quite some parts that are not strictly necessary which – if removed – might make it a bit less intimidating:

    1. None of the repositories have to be declared if you\’re using Boot GA versions.
    2. The project source encoding is already configured by the Boot parent pom for you.
    3. spring-data-commons gets pulled in by spring-data-couchbase transitively and thus doesn\’t necessarily have to be declared.

    That\’d pretty much cut the pom.xml down half in size and boil down to three dependencies and a plugin declaration. Still enough XML for my taste but less food for people to complain about Maven :).

    Looking forward to the next episodes!

  2. Eduardo Rodriguez October 7, 2015 at 4:53 pm

    I don\’t see there is a Health indicator for Couchbase DB.

  3. Arjun Kizhikkayil October 16, 2015 at 7:08 pm

    Hello i would like to add attachments to documents in couchbase using spring data jpa. But there is no methods like save or update for attachments

Leave a reply