Couchbase – How to create Spring JPA Couchbase application with SpringBoot

Couchbase server is an open source, distributed multi-model NoSQL document-oriented database. So in the tutorial, JavaSampleApproach will show you how to create a Spring JPA Couchbase with SpringBoot.

Related posts:
Couchbase – How to create Spring Cache Couchbase application with SpringBoot
How to use SpringData MongoRepository to interact with MongoDB
How to start Spring Data Cassandra with SpringBoot

I. Technologies

– Java 1.8
– Maven 3.3.9
– Spring Tool Suite – Version 3.8.1.RELEASE
– Spring Boot: 1.5.6RELEASE
– Couchbase 4.6.2

II. SpringBoot & Couchbase

Spring Boot provides auto-configuration for Couchbase and abstractions on top of it by Spring Data Couchbase. We can use it easily via spring-boot-starter-data-couchbase ‘Starter’ which had collected the needed dependencies.

Spring JPA Couchbase - SpringBoot - Architecture

For connecting with Couchbase Bucket and Cluster, we can use spring.couchbase.* properties in file:


For working with Couchbase repository, we use CouchbaseRepository interface:

public interface CouchbaseRepository extends CrudRepository {

   * @return a reference to the underlying {@link CouchbaseOperations operation template}.
  CouchbaseOperations getCouchbaseOperations();


***Note*** We can meet some problems when working with Couchbase database:

1. No view configuration => Exception:

Caused by: org.springframework.dao.InvalidDataAccessResourceUsageException: View customer/all does not exist.; nested exception is View customer/all does not exist.
	at ~[spring-data-couchbase-2.2.6.RELEASE.jar:na]
	at ~[spring-data-couchbase-2.2.6.RELEASE.jar:na]

2. No index => Exception:

Caused by: Unable to execute query due to the following n1ql errors: 
{"msg":"No index available on keyspace jsabucket that matches your query. Use CREATE INDEX or CREATE PRIMARY INDEX to create an index, or check that your expected index is online.","code":4000}

– Manually setup Couchbase view and create index
– Using SpringBoot support: @N1qlPrimaryIndexed annotation & configure to create views and indexs. is used to automatically create views and indexes. Use the meta-data provided by @ViewIndexed, @N1qlPrimaryIndexed and @N1qlSecondaryIndexed.

III. Practice

In the tutorial, we setup Couchbase 4.6.2 server and use SpringToolSuite to create SpringBoot project:

spring jpa couchbase - project structure

Step to do:
– Setup Couchbase 4.6.2 server
– Create SpringBoot project
– Create Couchbase model
– Create Couchbase repository
– Implement client
– Run & check results

1. Setup Couchbase 4.6.2 server

Download Couchbase at

couchbase download

Press Download -> Fill Info -> Try it now:

couchbase download - fill info

-> We got couchbase-server-enterprise_4.6.2-windows_amd64.exe file.

couchbase installer

Note: turn-off your virus protection programs before setup.

Right click on the installer for installing. Follow the installer prompts,

couchbase install

couchbase install-required

-> We got an Web-UI setup: at http://localhost:8091.

install couchebase server - web setup

Press Setup button.

couchbase server setup - web ui - 1
couchbase server setup - web ui - 2

Click Next to accept the default values for new cluster.

couchbase server setup - web ui - sample buckets - sample bucket

On Sample Buckets screen, click choose beer-sample and travel-sample and click Next, we got:

couchbase server setup - web ui - step 3-5

On above Create Default Bucket, under Memory Size set the Per Node RAM Quota to 100 MB and click Next, we got:

couchbase server setup - web ui - step 4-5

On above Notifications screen, enter your registration information then click Next, we got:

couchbase server setup - web ui - step 5-5

On the Configure Server screen, enter and verify a password for the administrator account, and click Next.
The Couchbase Web Console opens and displays the Cluster Overview:

couchbase server setup - web ui - final

-> Now Couchbase server is ready for use.

– Create jsabucket:

create jsa bucket

create jsa bucket - result

2. Create SpringBoot project

Using SpringToolSuite, create a SpringBoot project, then add needed dependency spring-data-couchbase:


3. Create Couchbase model

Create a Couchbase model Customer:

package com.javasampleapproach.couchbase.model;



public class Customer {
	private String id;

	private String firstName;

	private String lastName;
	public Customer(String id, String firstName, String lastName){ = id;
		this.firstName = firstName;
		this.lastName = lastName;
	public String getId() {

	public void setId(String id) { = id;

	public String getFirstName() {
		return this.firstName;

	public void setFirstName(String firstName) {
		this.firstName = firstName;

	public String getLastName() {
		return this.lastName;

	public void setLastName(String lastName) {
		this.lastName = lastName;

	public String toString() {
		return String.format("Customer[ id=%s, firstName=%s, lastName=%s]",, this.firstName, this.lastName);

4. Create Couchbase repository

– Create CustomerRepository repository:

package com.javasampleapproach.couchbase.repo;

import java.util.List;


import com.javasampleapproach.couchbase.model.Customer;

@ViewIndexed(designDoc = "customer", viewName = "all")
public interface CustomerRepository extends CouchbaseRepository {
	List findByLastName(String name);

– Open, add connection config:


5. Implement client

Using above CustomerRepository to implement client:

package com.javasampleapproach.couchbase;

import java.util.Arrays;
import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import com.javasampleapproach.couchbase.model.Customer;
import com.javasampleapproach.couchbase.repo.CustomerRepository;

public class SpringBootCouchbaseApplication implements CommandLineRunner {
	private CustomerRepository customerRepository;

	public static void main(String[] args) {, args);

	public void run(String... args) throws Exception {
		// delete all documents
		// save Customer to Couchbase Customer("01", "Jack", "Smith"),
												new Customer("02", "Adam", "Johnson"),
												new Customer("03", "Kim", "Smith"),
												new Customer("04", "David", "Williams"),
												new Customer("05", "Peter", "Davis")));
		System.out.println("=============Find All Customer=============");
		List custs = (List) customerRepository.findAll();
		custs = customerRepository.findByLastName("Smith");


6. Run & check results

Build and Run the SpringBoot project with commandlines {mvn clean install, mvn spring-boot:run}.

– Results:

-> Logs:

=============Find All Customer=============
Customer[ id=01, firstName=Jack, lastName=Smith]
Customer[ id=02, firstName=Adam, lastName=Johnson]
Customer[ id=03, firstName=Kim, lastName=Smith]
Customer[ id=04, firstName=David, lastName=Williams]
Customer[ id=05, firstName=Peter, lastName=Davis]
Customer[ id=01, firstName=Jack, lastName=Smith]
Customer[ id=03, firstName=Kim, lastName=Smith]

-> all view is auto-created by the SpringBoot application.

couchbase productview - all

-> Query with Couchbase:

couchbase select all

IV. Sourcecode


By grokonez | August 22, 2017.

Last updated on April 10, 2021.

Related Posts

2 thoughts on “Couchbase – How to create Spring JPA Couchbase application with SpringBoot”

Got Something To Say:

Your email address will not be published. Required fields are marked *