Migrating from Spring Data Couchbase 3.x to 4.x

This chapter is a quick reference of what major changes have been introduced in 4.x and gives a high-level overview of things to consider when migrating.

Please note that implicitly the minimum Couchbase Server version has been bumped up to 5.5 and later, and we recommend running at least 6.0.x.

Configuration

Since the main objective was to migrate from the Java SDK 2 to 3, configuration has changed to adapt to the new SDK and also in the long run to prepare it for scopes and collections (but it can still be used without collection support).

XML Configuration support has been dropped, so only java/annotation based configuration is supported.

Your configuration still has to extend the AbstractCouchbaseConfiguration, but since RBAC (role-based access control) is now mandatory, different properties need to be overridden in order to be configured: getConnectionString, getUserName, getPassword and getBucketName.If you want to use a non-default scope optionally you can override the getScopeName method.Note that if you want to use certificate based authentication or you need to customize the password authentication, the authenticator method can be overridden to perform this task.

The new SDK still has an environment that is used to configure it, so you can override the configureEnvironment method and supply custom configuration if needed.

For more information, see Installation & Configuration.

Spring Boot Version Compatibility

Spring Boot 2.3.x or higher depends on Spring Data Couchbase 4.x.Earlier versions of Couchbase are not available because SDK 2 and 3 cannot live on the same classpath.

Entities

How to deal with entities has not changed, although since the SDK now does not ship annotations anymore only Spring-Data related annotations are supported.

Specifically:

com.couchbase.client.java.repository.annotation.Id became import org.springframework.data.annotation.Id
com.couchbase.client.java.repository.annotation.Field became import org.springframework.data.couchbase.core.mapping.Field

The org.springframework.data.couchbase.core.mapping.Document annotation stayed the same.

For more information, see Modeling Entities.

Automatic Index Management

Automatic Index Management has been redesigned to allow more flexible indexing. New annotations have been introduced and old ones like @ViewIndexed, @N1qlSecondaryIndexed and @N1qlPrimaryIndexed were removed.

For more information, see Automatic Index Management.

Template and ReactiveTemplate

Since the Couchbase SDK 3 removes support for RxJava and instead adds support for Reactor, both the couchbaseTemplate as well as the reactiveCouchbaseTemplate can be directly accessed from the AbstractCouchbaseConfiguration.

The template has been completely overhauled so that it now uses a fluent API to configure instead of many method overloads.This has the advantage that in the future we are able to extend the functionality without having to introduce more and more overloads that make it complicated to navigate.

The following table describes the method names in 3.x and compares them to their 4.x equivalents:

Table 1. Template Method Comparison
SDC 3.x	SDC 4.x
save	upsertById
insert	insertById
update	replaceById
findById	findById
findByView	(removed)
findBySpatialView	(removed)
findByN1QL	findByQuery
findByN1QLProjection	findByQuery
queryN1QL	(call SDK directly)
exists	existsById
remove	removeById
execute	(call SDK directly)

In addition, the following methods have been added which were not available in 3.x:

Table 2. Template Additions in 4.x
Name	Description
removeByQuery	Allows to remove entities through a N1QL query
findByAnalytics	Performs a find through the analytics service
findFromReplicasById	Like findById, but takes replicas into account

We tried to unify and align the APIs more closely to the underlying SDK semantics so they are easier to correlate and navigate.

For more information, see Template & direct operations.

Repositories & Queries

org.springframework.data.couchbase.core.query.Query became org.springframework.data.couchbase.repository.Query
org.springframework.data.couchbase.repository.ReactiveCouchbaseSortingRepository has been removed.Consider extending ReactiveSortingRepository or ReactiveCouchbaseRepository
org.springframework.data.couchbase.repository.CouchbasePagingAndSortingRepository has been removed.Consider extending PagingAndSortingRepository or CouchbaseRepository

Support for views has been removed and N1QL queries are now the first-class citizens for all custom repository methods as well as the built-in ones by default.

The behavior itself has not changed over the previous version on how the query derivation is supposed to work. Should you encounter any queries that worked in the past and now do not work anymore please let us know.

It is possible to override the default scan consistency for N1QL queries through the new ScanConsistency annotation.

The method getCouchbaseOperations() has also been removed. You can still access all methods from the native Java SDK via the class CouchbaseTemplate or Cluster:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.couchbase.core.CouchbaseTemplate;
import org.springframework.stereotype.Service;
import com.couchbase.client.java.Cluster;

@Service
public class MyService {

    @Autowired
    private CouchbaseTemplate couchbaseTemplate;

    @Autowired
    private Cluster cluster;
}

See Couchbase repositories for more information.

Full Text Search (FTS)

The FTS API has been simplified and now can be accessed via the Cluster class:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.couchbase.client.java.Cluster;
import com.couchbase.client.java.search.result.SearchResult;
import com.couchbase.client.java.search.result.SearchRow;
import com.couchbase.client.core.error.CouchbaseException;

@Service
public class MyService {

    @Autowired
    private Cluster cluster;

    public void myMethod() {
        try {
          final SearchResult result = cluster
            .searchQuery("index", SearchQuery.queryString("query"));

          for (SearchRow row : result.rows()) {
            System.out.println("Found row: " + row);
          }

          System.out.println("Reported total rows: "
            + result.metaData().metrics().totalRows());
        } catch (CouchbaseException ex) {
          ex.printStackTrace();
        }
    }
}

See the FTS Documentation for more information.