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).

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.

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:

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

For more information, see Modeling Entities.

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.

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:

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

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.

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:

See Couchbase repositories for more information.

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

See the FTS Documentation for more information.

Unresolved directive in index.adoc - include::../../../../spring-data-commons/src/main/asciidoc/upgrade.adoc[leveloffset=+1]

All versions intended for production use are distributed across Maven Central and the Spring release repository. As a result, the library can be included like any other maven dependency:

This will pull in several dependencies, including the underlying Couchbase Java SDK, common Spring dependencies and also Jackson as the JSON mapping infrastructure.

You can also grab snapshots from the spring snapshot repository ( https://repo.spring.io/libs-snapshot ) and milestone releases from the spring milestone repository ( https://repo.spring.io/libs-milestone ). Here is an example on how to use the current SNAPSHOT dependency:

Once you have all needed dependencies on the classpath, you can start configuring it. Only Java config is supported (XML config has been removed in 4.0).

To get started, all you need to do is subclcass the AbstractCouchbaseConfiguration and implement the abstract methods.

The connection string is made up of a list of hosts and an optional scheme (couchbase://) as shown in the code above. All you need to provide is a list of Couchbase nodes to bootstrap into (separated by a ,). Please note that while one host is sufficient in development, it is recommended to add 3 to 5 bootstrap nodes here. Couchbase will pick up all nodes from the cluster automatically, but it could be the case that the only node you’ve provided is experiencing issues while you are starting the application.

The userName and password are configured in your Couchbase Server cluster through RBAC (role-based access control). The bucketName reflects the bucket you want to use for this configuration.

Additionally, the SDK environment can be tuned by overriding the configureEnvironment method which takes a ClusterEnvironment.Builder to return a configured ClusterEnvironment.

Many more things can be customized and overridden as custom beans from this configuration (for example repositories, validation and custom converters).

If you start your application, you should see Couchbase INFO level logging in the logs, indicating that the underlying Couchbase Java SDK is connecting to the database. If any errors are reported, make sure that the given credentials and host information are correct.

All entities should be annotated with the @Document annotation, but it is not a requirement.

Also, every field in the entity should be annotated with the @Field annotation. While this is - strictly speaking - optional, it helps to reduce edge cases and clearly shows the intent and design of the entity. It can also be used to store the field under a different name.

There is also a special @Id annotation which needs to be always in place. Best practice is to also name the property id.

Here is a very simple User entity:

Couchbase Server supports automatic expiration for documents. The library implements support for it through the @Document annotation. You can set a expiry value which translates to the number of seconds until the document gets removed automatically. If you want to make it expire in 10 seconds after mutation, set it like @Document(expiry = 10). Alternatively, you can configure the expiry using Spring’s property support and the expiryExpression parameter, to allow for dynamically changing the expiry value. For example: @Document(expiryExpression = "${valid.document.expiry}"). The property must be resolvable to an int value and the two approaches cannot be mixed.

If you want a different representation of the field name inside the document in contrast to the field name used in your entity, you can set a different name on the @Field annotation. For example if you want to keep your documents small you can set the firstname field to @Field("fname"). In the JSON document, you’ll see {"fname": ".."} instead of {"firstname": ".."}.

The @Id annotation needs to be present because every document in Couchbase needs a unique key. This key needs to be any string with a length of maximum 250 characters. Feel free to use whatever fits your use case, be it a UUID, an email address or anything else.

Writes to Couchbase-Server buckets can optionally be assigned durability requirements; which instruct Couchbase Server to update the specified document on multiple nodes in memory and/or disk locations across the cluster; before considering the write to be committed. Default durability requirements can also be configured through the @Document annotation. For example: @Document(durabilityLevel = DurabilityLevel.MAJORITY) will force mutations to be replicated to a majority of the Data Service nodes.

The storage format of choice is JSON. It is great, but like many data representations it allows less datatypes than you could express in Java directly. Therefore, for all non-primitive types some form of conversion to and from supported types needs to happen.

For the following entity field types, you don’t need to add special handling:

Since JSON supports objects ("maps") and lists, Map and List types can be converted naturally. If they only contain primitive field types from the last paragraph, you don’t need to add special handling too. Here is an example:

Storing a user with some sample data could look like this as a JSON representation:

You don’t need to break everything down to primitive types and Lists/Maps all the time. Of course, you can also compose other objects out of those primitive values. Let’s modify the last example so that we want to store a List of Children:

A populated object can look like:

Most of the time, you also need to store a temporal value like a Date. Since it can’t be stored directly in JSON, a conversion needs to happen. The library implements default converters for Date, Calendar and JodaTime types (if on the classpath). All of those are represented by default in the document as a unix timestamp (number). You can always override the default behavior with custom converters as shown later. Here is an example:

A populated object can look like:

Optionally, Date can be converted to and from ISO-8601 compliant strings by setting system property org.springframework.data.couchbase.useISOStringConverterForDate to true. If you want to override a converter or implement your own one, this is also possible. The library implements the general Spring Converter pattern. You can plug in custom converters on bean creation time in your configuration. Here’s how you can configure it (in your overridden AbstractCouchbaseConfiguration):

There are a few things to keep in mind with custom conversions:

In certain situations you may want to ensure that you are not overwriting another users changes when you perform a mutation operation on a document. For this you have three choices: Transactions (since Couchbase 6.5), pessimistic concurrency (locking) or optimistic concurrency.

Optimistic concurrency tends to provide better performance than pessimistic concurrency or transactions, because no actual locks are held on the data and no extra information is stored about the operation (no transaction log).

To implement optimistic locking, Couchbase uses a CAS (compare and swap) approach. When a document is mutated, the CAS value also changes. The CAS is opaque to the client, the only thing you need to know is that it changes when the content or a meta information changes too.

In other datastores, similar behavior can be achieved through an arbitrary version field with a incrementing counter. Since Couchbase supports this in a much better fashion, it is easy to implement. If you want automatic optimistic locking support, all you need to do is add a @Version annotation on a long field like this:

If you load a document through the template or repository, the version field will be automatically populated with the current CAS value. It is important to note that you shouldn’t access the field or even change it on your own. Once you save the document back, it will either succeed or fail with a OptimisticLockingFailureException. If you get such an exception, the further approach depends on what you want to achieve application wise. You should either retry the complete load-update-write cycle or propagate the error to the upper layers for proper handling.

The library supports JSR 303 validation, which is based on annotations directly in your entities. Of course you can add all kinds of validation in your service layer, but this way its nicely coupled to your actual entities.

To make it work, you need to include two additional dependencies. JSR 303 and a library that implements it, like the one supported by hibernate:

Now you need to add two beans to your configuration:

Now you can annotate your fields with JSR303 annotations. If a validation on save() fails, a ConstraintViolationException is thrown.

Entities can be automatically audited (tracing which user created the object, updated the object, and at what times) through Spring Data auditing mechanisms.

First, note that only entities that have a @Version annotated field can be audited for creation (otherwise the framework will interpret a creation as an update).

Auditing works by annotating fields with @CreatedBy, @CreatedDate, @LastModifiedBy and @LastModifiedDate. The framework will automatically inject the correct values on those fields when persisting the entity. The xxxDate annotations must be put on a Date field (or compatible, eg. jodatime classes) while the xxxBy annotations can be put on fields of any class T (albeit both fields must be of the same type).

To configure auditing, first you need to have an auditor aware bean in the context. Said bean must be of type AuditorAware<T> (allowing to produce a value that can be stored in the xxxBy fields of type T we saw earlier). Secondly, you must activate auditing in your @Configuration class by using the @EnableCouchbaseAuditing annotation.

Here is an example:

Notice both @CreatedBy and @LastModifiedBy are both put on a String field, so our AuditorAware must work with String.

To tie all that together, we use the java configuration both to declare an AuditorAware bean and to activate auditing:

Keys to be auto-generated should be annotated with @GeneratedValue. The default strategy is USE_ATTRIBUTES. Prefix and suffix for the key can be provided as part of the entity itself, these values are not persisted, they are only used for key generation. The prefixes and suffixes are ordered using the order value. The default order is 0, multiple prefixes without order will overwrite the previous. If a value for id is already available, auto-generation will be skipped. The delimiter for concatenation can be provided using delimiter, the default delimiter is ..

It is a common practice to generate keys using a combination of the document attributes. Key generation using attributes concatenates all the attribute values annotated with IdAttribute, based on the ordering provided similar to prefixes and suffixes.

This auto-generation uses UUID random generator to generate document keys consuming 16 bytes of key space. This mechanism is only recommended for test scaffolding.

Unresolved directive in index.adoc - include::../../../../spring-data-commons/src/main/asciidoc/repositories.adoc[]

While support for repositories is always present, you need to enable them in general or for a specific namespace. If you extend AbstractCouchbaseConfiguration, just use the @EnableCouchbaseRepositories annotation. It provides lots of possible options to narrow or customize the search path, one of the most common ones is basePackages.

Also note that if you are running inside spring boot, the autoconfig support already sets up the annotation for you so you only need to use it if you want to override the defaults.

An advanced usage is described in [couchbase.repository.multibucket].

In the simplest case, your repository will extend the CrudRepository<T, String>, where T is the entity that you want to expose. Let’s look at a repository for a UserInfo:

Please note that this is just an interface and not an actual class. In the background, when your context gets initialized, actual implementations for your repository descriptions get created and you can access them through regular beans. This means you will save lots of boilerplate code while still exposing full CRUD semantics to your service layer and application.

Now, let’s imagine we @Autowire the UserRepository to a class that makes use of it. What methods do we have available?

Now that’s awesome! Just by defining an interface we get full CRUD functionality on top of our managed entity.

While the exposed methods provide you with a great variety of access patterns, very often you need to define custom ones. You can do this by adding method declarations to your interface, which will be automatically resolved to requests in the background, as we’ll see in the next sections.

This chapter describes the reactive repository support for couchbase. This builds on the core repository support explained in Couchbase repositories. So make sure you’ve got a sound understanding of the basic concepts explained there.

The Couchbase Java SDK 3.x moved from RxJava to Reactor, so it blends in very nicely with the reactive spring ecosystem.

Reactive Couchbase repositories provide project Reactor wrapper types and can be used by simply extending from one of the library-specific repository interfaces:

Let’s create a simple entity to start with:

A corresponding repository implementation may look like this:

For JavaConfig use the @EnableReactiveCouchbaseRepositories annotation. The annotation carries the very same attributes like the namespace element. If no base package is configured the infrastructure will scan the package of the annotated configuration class.

Also note that if you are using it in a spring boot setup you likely can omit the annotation since it is autoconfigured for you.

As our domain repository extends ReactiveSortingRepository it provides you with CRUD operations as well as methods for sorted access to the entities. Working with the repository instance is just a matter of dependency injecting it into a client.

Spring Data’s Reactive Couchbase comes with full querying support already provided by the blocking Repositories and Querying

The template can be accessed through the couchbaseTemplate and reactiveCouchbaseTemplate beans out of your context. Once you’ve got a reference to it, you can run all kinds of operations against it. Other than through a repository, in a template you need to always specify the target entity type which you want to get converted.

The templates use a fluent-style API which allows you to chain in optional operators as needed. As an example, here is how you store a user and then find it again by its ID:

If you wanted to use a custom (by default durability options from the @Document annotation will be used) durability requirement for the upsert operation you can chain it in:

In a similar fashion, you can perform a N1QL operation:

Couchbase supports Sub-Document Operations. This section documents how to use it with Spring Data Couchbase.

Sub-Document operations may be quicker and more network-efficient than full-document operations such as upsert or replace because they only transmit the accessed sections of the document over the network.

Sub-Document operations are also atomic, in that if one Sub-Document mutation fails then all will, allowing safe modifications to documents with built-in concurrency control.

Currently Spring Data Couchbase supports only sub document mutations (remove, upsert, replace and insert).

Mutation operations modify one or more paths in the document. The simplest of these operations is upsert, which, similar to the fulldoc-level upsert, will either modify the value of an existing path or create it if it does not exist:

Following example will upsert the city field on the address of the user, without trasfering any additional user document data.

The Spring Data Couchbase template operations insert, find, replace and delete and repository methods that use those calls can participate in a Couchbase Transaction. They can be executed in a transaction by using the @Transactional annotation, the CouchbaseTransactionalOperator, or in the lambda of a Couchbase Transaction.

Couchbase Transactions are normally leveraged with a method annotated with @Transactional. The @Transactional operator is implemented with the CouchbaseTransactionManager which is supplied as a bean in the AbstractCouchbaseConfiguration. Couchbase Transactions can be used without defining a service class by using CouchbaseTransactionOperator which is also supplied as a bean in AbtractCouchbaseConfiguration. Couchbase Transactions can also be used directly using Spring Data Couchbase operations within a lambda Using Transactions

@Transactional defines as transactional a method or all methods on a class.

When this annotation is declared at the class level, it applies as a default to all methods of the declaring class and its subclasses.

CouchbaseTransactionalOperator can be used to construct a transaction in-line without creating a service class that uses @Transactional. CouchbaseTransactionalOperator is available as a bean and can be instantiated with @Autowired. If creating one explicitly, it must be created with CouchbaseTransactionalOperator.create(manager) (NOT TransactionalOperator.create(manager)).

Spring Data Couchbase works seamlessly with the Couchbase Java SDK for transaction processing. Spring Data Couchbase operations that can be executed in a transaction will work directly within the lambda of a transactions().run() without involving any of the Spring Transactions mechanisms. This is the most straight-forward way to leverage Couchbase Transactions in Spring Data Couchbase.

Please see the Reference Documentation

Fields annotated with com.couchbase.client.java.encryption.annotation.Encrypted (@Encrypted) will be automatically encrypted on write and decrypted on read. Unencrypted fields can be migrated to encrypted by specifying @Encrypted(migration = Encrypted.Migration.FROM_UNENCRYPTED).

Associated entities can be fetched by annotating the entity’s property reference with @N1qlJoin. The prefix lks refers to left-hand side key space (current entity) and rks refers to the right-hand side key space (associated entity). The required element for @N1qlJoin annotation is the on clause, a boolean expression representing the join condition between the left-hand side (lks) and the right-hand side (rks), which can be fields, constant expressions or any complex N1QL expression. There could also be an optional where clause specified on the annotation for the join, similarly using lks to refer the current entity and rks to refer the associated entity.

Associated entities can be lazily fetched upon the first access of the property, this could save on fetching more data than required when loading the entity. To load the associated entities lazily, @N1qlJoin annotation’s element fetchType has to be set to FetchType.LAZY. The default is FetchType.IMMEDIATE.

Technically, caching is not part of spring-data, but is implemented directly in the spring core. Most database implementations in the spring-data package can’t support @Cacheable, because it is not possible to store arbitrary data.

Couchbase supports both binary and JSON data, so you can get both out of the same database.

To make it work, you need to add the @EnableCaching annotation and configure the cacheManager bean:

The persistent identifier can then be used on the @Cacheable annotation to identify the cache manager to use (you can have more than one configured).

Once it is set up, you can annotate every method with the @Cacheable annotation to transparently cache it in your couchbase bucket. You can also customize how the key is generated.

If you run the method multiple times, you’ll see a set operation happening first, followed by multiple get operations and no sleep time (which fakes the expensive execution). You can store whatever you want, if it is JSON of course you can access it through views and look at it in the Web UI.

Note that to use cache.clear() or catch.invalidate(), the bucket must have a primary key. :leveloffset: -1