0
# Spring Boot Starter Data Couchbase Reactive
1

2
## Overview
3

4
The Spring Boot Starter Data Couchbase Reactive provides seamless integration for reactive Couchbase database operations in Spring Boot applications. This starter automatically configures Spring Data Couchbase with reactive support using Project Reactor, enabling non-blocking database interactions with Couchbase NoSQL databases.
5

6
Key features:
7
- Auto-configuration of reactive Couchbase templates and repositories
8
- Built-in connection pool management and clustering support
9
- Integration with Project Reactor (Mono/Flux) and RxJava reactive streams
10
- Comprehensive configuration properties for fine-tuning connection behavior
11
- Built-in health checks and metrics support
12

13
## Package Information
14

15
- **Package Name**: spring-boot-starter-data-couchbase-reactive
16
- **Package Type**: maven
17
- **Language**: Java
18
- **Installation**: Add to `pom.xml` or `build.gradle` dependencies
19

20
### Maven
21
```xml
22
<dependency>
23
    <groupId>org.springframework.boot</groupId>
24
    <artifactId>spring-boot-starter-data-couchbase-reactive</artifactId>
25
</dependency>
26
```
27

28
### Gradle
29
```gradle
30
implementation 'org.springframework.boot:spring-boot-starter-data-couchbase-reactive'
31
```
32

33
## Core Imports
34

35
```java
36
// Reactive template for programmatic database access
37
import org.springframework.data.couchbase.core.ReactiveCouchbaseTemplate;
38

39
// Base reactive repository interface
40
import org.springframework.data.couchbase.repository.ReactiveCouchbaseRepository;
41

42
// Configuration properties
43
import org.springframework.boot.autoconfigure.couchbase.CouchbaseProperties;
44
import org.springframework.boot.autoconfigure.data.couchbase.CouchbaseDataProperties;
45

46
// Document mapping annotations
47
import org.springframework.data.couchbase.core.mapping.Document;
48
import org.springframework.data.couchbase.core.mapping.Field;
49
import org.springframework.data.annotation.Id;
50

51
// Reactive types
52
import reactor.core.publisher.Mono;
53
import reactor.core.publisher.Flux;
54

55
// Test support
56
import org.springframework.boot.test.autoconfigure.data.couchbase.DataCouchbaseTest;
57
```
58

59
## Basic Usage
60

61
### 1. Configuration
62

63
Configure Couchbase connection in `application.yml`:
64

65
```yaml
66
spring:
67
  couchbase:
68
    connection-string: couchbase://localhost
69
    username: admin
70
    password: password
71
  data:
72
    couchbase:
73
      bucket-name: my-bucket
74
      auto-index: true
75
```
76

77
### 2. Entity Definition
78

79
```java { .api }
80
import org.springframework.data.couchbase.core.mapping.Document;
81
import org.springframework.data.couchbase.core.mapping.Field;
82
import org.springframework.data.annotation.Id;
83

84
/**
85
 * Couchbase document entity
86
 */
87
@Document
88
public class User {
89
    
90
    @Id
91
    private String id;
92
    
93
    @Field
94
    private String name;
95
    
96
    @Field  
97
    private String email;
98
    
99
    // Constructors, getters, setters
100
    public User() {}
101
    
102
    public User(String name, String email) {
103
        this.name = name;
104
        this.email = email;
105
    }
106
    
107
    public String getId() { return id; }
108
    public void setId(String id) { this.id = id; }
109
    
110
    public String getName() { return name; }
111
    public void setName(String name) { this.name = name; }
112
    
113
    public String getEmail() { return email; }
114
    public void setEmail(String email) { this.email = email; }
115
}
116
```
117

118
### 3. Reactive Repository
119

120
```java { .api }
121
import org.springframework.data.couchbase.repository.ReactiveCouchbaseRepository;
122
import reactor.core.publisher.Flux;
123
import reactor.core.publisher.Mono;
124

125
/**
126
 * Reactive repository interface for User documents
127
 * Provides reactive CRUD operations and custom query methods
128
 */
129
public interface UserRepository extends ReactiveCouchbaseRepository<User, String> {
130
    
131
    /**
132
     * Find users by name reactively
133
     * @param name the name to search for
134
     * @return Flux of matching users
135
     */
136
    Flux<User> findByName(String name);
137
    
138
    /**
139
     * Find user by email reactively  
140
     * @param email the email to search for
141
     * @return Mono of matching user or empty
142
     */
143
    Mono<User> findByEmail(String email);
144
    
145
    /**
146
     * Check if user exists by email
147
     * @param email the email to check
148
     * @return Mono of boolean indicating existence
149
     */
150
    Mono<Boolean> existsByEmail(String email);
151
}
152
```
153

154
### 4. Service Using Reactive Template
155

156
```java { .api }
157
import org.springframework.data.couchbase.core.ReactiveCouchbaseTemplate;
158
import org.springframework.stereotype.Service;
159
import reactor.core.publisher.Mono;
160
import reactor.core.publisher.Flux;
161

162
/**
163
 * Service demonstrating reactive template usage
164
 */
165
@Service
166
public class UserService {
167
    
168
    private final ReactiveCouchbaseTemplate reactiveCouchbaseTemplate;
169
    
170
    public UserService(ReactiveCouchbaseTemplate reactiveCouchbaseTemplate) {
171
        this.reactiveCouchbaseTemplate = reactiveCouchbaseTemplate;
172
    }
173
    
174
    /**
175
     * Save user document reactively
176
     * @param user the user to save
177
     * @return Mono of saved user
178
     */
179
    public Mono<User> saveUser(User user) {
180
        return reactiveCouchbaseTemplate.save(user);
181
    }
182
    
183
    /**
184
     * Find user by ID reactively
185
     * @param id the user ID
186
     * @return Mono of user or empty
187
     */
188
    public Mono<User> findUserById(String id) {
189
        return reactiveCouchbaseTemplate.findById(User.class).one(id);
190
    }
191
    
192
    /**
193
     * Find all users reactively
194
     * @return Flux of all users
195
     */
196
    public Flux<User> findAllUsers() {
197
        return reactiveCouchbaseTemplate.findAll(User.class);
198
    }
199
    
200
    /**
201
     * Delete user by ID reactively
202
     * @param id the user ID to delete
203
     * @return Mono of void indicating completion
204
     */
205
    public Mono<Void> deleteUser(String id) {
206
        return reactiveCouchbaseTemplate.removeById().one(id).then();
207
    }
208
}
209
```
210

211
## Configuration Properties
212

213
### Couchbase Connection (`spring.couchbase`)
214

215
```java { .api }
216
/**
217
 * Primary Couchbase connection configuration
218
 */
219
public class CouchbaseProperties {
220
    
221
    /**
222
     * Connection string used to locate the Couchbase cluster
223
     * Example: "couchbase://localhost" or "couchbase://node1,node2"
224
     */
225
    private String connectionString;
226
    
227
    /**
228
     * Cluster username for authentication
229
     */
230
    private String username;
231
    
232
    /**
233
     * Cluster password for authentication  
234
     */
235
    private String password;
236
    
237
    /**
238
     * Environment configuration for fine-tuning
239
     */
240
    private Env env = new Env();
241
}
242
```
243

244
### Environment Configuration (`spring.couchbase.env`)
245

246
#### I/O Settings (`spring.couchbase.env.io`)
247
```java { .api }
248
public class Io {
249
    /**
250
     * Minimum number of sockets per node (default: 1)
251
     */
252
    private int minEndpoints = 1;
253
    
254
    /**
255
     * Maximum number of sockets per node (default: 12)  
256
     */
257
    private int maxEndpoints = 12;
258
    
259
    /**
260
     * HTTP connection idle timeout (default: 4500ms)
261
     */
262
    private Duration idleHttpConnectionTimeout = Duration.ofMillis(4500);
263
}
264
```
265

266
#### SSL Configuration (`spring.couchbase.env.ssl`)
267
```java { .api }
268
public class Ssl {
269
    /**
270
     * Enable SSL support (auto-detected if keyStore provided)
271
     */
272
    private Boolean enabled;
273
    
274
    /**
275
     * Path to JVM key store with certificates
276
     */
277
    private String keyStore;
278
    
279
    /**
280
     * Password for key store access
281
     */
282
    private String keyStorePassword;
283
}
284
```
285

286
#### Timeout Configuration (`spring.couchbase.env.timeouts`)
287
```java { .api }
288
public class Timeouts {
289
    /**
290
     * Bucket connect timeout (default: 10s)
291
     */
292
    private Duration connect = Duration.ofSeconds(10);
293
    
294
    /**
295
     * Bucket disconnect timeout (default: 10s)
296
     */
297
    private Duration disconnect = Duration.ofSeconds(10);
298
    
299
    /**
300
     * Key-value operations timeout (default: 2500ms)
301
     */
302
    private Duration keyValue = Duration.ofMillis(2500);
303
    
304
    /**
305
     * Durable key-value operations timeout (default: 10s)
306
     */
307
    private Duration keyValueDurable = Duration.ofSeconds(10);
308
    
309
    /**
310
     * N1QL query operations timeout (default: 75s)
311
     */
312
    private Duration query = Duration.ofSeconds(75);
313
    
314
    /**
315
     * View operations timeout (default: 75s)
316
     */
317
    private Duration view = Duration.ofSeconds(75);
318
    
319
    /**
320
     * Search service timeout (default: 75s)
321
     */
322
    private Duration search = Duration.ofSeconds(75);
323
    
324
    /**
325
     * Analytics service timeout (default: 75s)
326
     */
327
    private Duration analytics = Duration.ofSeconds(75);
328
    
329
    /**
330
     * Management operations timeout (default: 75s)
331
     */
332
    private Duration management = Duration.ofSeconds(75);
333
}
334
```
335

336
### Data Layer Configuration (`spring.data.couchbase`)
337

338
```java { .api }
339
/**
340
 * Spring Data Couchbase specific configuration
341
 */
342
public class CouchbaseDataProperties {
343
    
344
    /**
345
     * Automatically create views and indexes using annotations
346
     * Uses @ViewIndexed, @N1qlPrimaryIndexed, @N1qlSecondaryIndexed
347
     */
348
    private boolean autoIndex = false;
349
    
350
    /**
351
     * Name of the bucket to connect to
352
     */
353
    private String bucketName;
354
    
355
    /**
356
     * Name of the scope for collection access
357
     */
358
    private String scopeName;
359
    
360
    /**
361
     * Field storing type information for complex types (default: "_class")
362
     */
363
    private String typeKey = "_class";
364
    
365
    /**
366
     * Fully qualified FieldNamingStrategy class name for field name mapping
367
     */
368
    private Class<?> fieldNamingStrategy;
369
}
370
```
371

372
## Reactive Template Operations
373

374
### Basic CRUD Operations
375

376
```java { .api }
377
/**
378
 * ReactiveCouchbaseTemplate provides programmatic database access
379
 */
380
public class ReactiveCouchbaseTemplate {
381
    
382
    /**
383
     * Save a document reactively
384
     * @param entity the entity to save
385
     * @return Mono of saved entity
386
     */
387
    public <T> Mono<T> save(T entity);
388
    
389
    /**
390
     * Find document by ID reactively
391
     * @param entityClass the entity class
392
     * @return FindByIdOperation for method chaining
393
     */
394
    public <T> FindByIdOperation<T> findById(Class<T> entityClass);
395
    
396
    /**
397
     * Find all documents of type reactively
398
     * @param entityClass the entity class
399
     * @return Flux of all entities
400
     */
401
    public <T> Flux<T> findAll(Class<T> entityClass);
402
    
403
    /**
404
     * Remove document by ID reactively
405
     * @return RemoveByIdOperation for method chaining
406
     */
407
    public RemoveByIdOperation removeById();
408
}
409
```
410

411
### Advanced Query Operations
412

413
```java { .api }
414
/**
415
 * Advanced reactive query operations
416
 */
417
public interface ReactiveQueryOperations {
418
    
419
    /**
420
     * Execute N1QL query reactively
421
     * @param query the N1QL query string
422
     * @param entityClass the result entity class
423
     * @return Flux of query results
424
     */
425
    public <T> Flux<T> findByQuery(String query, Class<T> entityClass);
426
    
427
    /**
428
     * Execute view query reactively
429
     * @param viewName the view name
430
     * @param entityClass the result entity class  
431
     * @return Flux of view results
432
     */
433
    public <T> Flux<T> findByView(String viewName, Class<T> entityClass);
434
}
435
```
436

437
## Repository Interface Hierarchy
438

439
### Base Repository Interface
440

441
```java { .api }
442
/**
443
 * Base reactive repository interface providing standard CRUD operations
444
 * @param <T> the domain type
445
 * @param <ID> the ID type
446
 */
447
public interface ReactiveCouchbaseRepository<T, ID> {
448
    
449
    /**
450
     * Save entity reactively
451
     * @param entity the entity to save
452
     * @return Mono of saved entity
453
     */
454
    <S extends T> Mono<S> save(S entity);
455
    
456
    /**
457
     * Save multiple entities reactively
458
     * @param entities the entities to save
459
     * @return Flux of saved entities
460
     */
461
    <S extends T> Flux<S> saveAll(Iterable<S> entities);
462
    
463
    /**
464
     * Find entity by ID reactively
465
     * @param id the entity ID
466
     * @return Mono of entity or empty
467
     */
468
    Mono<T> findById(ID id);
469
    
470
    /**
471
     * Check if entity exists by ID
472
     * @param id the entity ID
473
     * @return Mono of boolean indicating existence
474
     */
475
    Mono<Boolean> existsById(ID id);
476
    
477
    /**
478
     * Find all entities reactively
479
     * @return Flux of all entities
480
     */
481
    Flux<T> findAll();
482
    
483
    /**
484
     * Count all entities reactively
485
     * @return Mono of total count
486
     */
487
    Mono<Long> count();
488
    
489
    /**
490
     * Delete entity by ID reactively
491
     * @param id the entity ID
492
     * @return Mono of void indicating completion
493
     */
494
    Mono<Void> deleteById(ID id);
495
    
496
    /**
497
     * Delete entity reactively
498
     * @param entity the entity to delete
499
     * @return Mono of void indicating completion
500
     */
501
    Mono<Void> delete(T entity);
502
    
503
    /**
504
     * Delete all entities reactively
505
     * @return Mono of void indicating completion
506
     */
507
    Mono<Void> deleteAll();
508
}
509
```
510

511
## Auto-Configuration Beans
512

513
### Primary Configuration Beans
514

515
```java { .api }
516
/**
517
 * Key beans automatically configured by the starter
518
 */
519

520
/**
521
 * Main reactive template bean for database operations
522
 * Bean name: "reactiveCouchbaseTemplate"
523
 */
524
@Bean(name = BeanNames.REACTIVE_COUCHBASE_TEMPLATE)
525
public ReactiveCouchbaseTemplate reactiveCouchbaseTemplate(
526
    CouchbaseClientFactory couchbaseClientFactory,
527
    MappingCouchbaseConverter mappingCouchbaseConverter);
528

529
/**
530
 * Repository operations mapping for reactive repositories
531
 * Bean name: "reactiveCouchbaseRepositoryOperationsMapping"  
532
 */
533
@Bean(name = BeanNames.REACTIVE_COUCHBASE_OPERATIONS_MAPPING)
534
public ReactiveRepositoryOperationsMapping reactiveCouchbaseRepositoryOperationsMapping(
535
    ReactiveCouchbaseTemplate reactiveCouchbaseTemplate);
536

537
/**
538
 * Cluster environment with I/O, SSL, and timeout configuration
539
 * Bean name: "couchbaseClusterEnvironment"
540
 */
541
@Bean(destroyMethod = "shutdown")
542
public ClusterEnvironment couchbaseClusterEnvironment(
543
    CouchbaseProperties properties);
544

545
/**
546
 * Couchbase cluster client connection
547
 * Bean name: "couchbaseCluster"
548
 */
549
@Bean(destroyMethod = "disconnect")
550
public Cluster couchbaseCluster(
551
    ClusterEnvironment clusterEnvironment,
552
    CouchbaseProperties properties);
553

554
/**
555
 * Client factory for bucket access
556
 * Bean name: "couchbaseClientFactory"
557
 */
558
@Bean
559
public CouchbaseClientFactory couchbaseClientFactory(
560
    Cluster couchbaseCluster,
561
    CouchbaseDataProperties properties);
562

563
/**
564
 * Object mapping converter for document serialization
565
 * Bean name: "couchbaseMappingConverter"
566
 */
567
@Bean
568
public MappingCouchbaseConverter couchbaseMappingConverter(
569
    CouchbaseMappingContext mappingContext,
570
    CouchbaseCustomConversions customConversions);
571

572
/**
573
 * Custom type conversions for reactive operations
574
 * Bean name: "couchbaseCustomConversions"
575
 */
576
@Bean
577
public CouchbaseCustomConversions couchbaseCustomConversions();
578

579
/**
580
 * JSR-303 validation event listener for reactive operations
581
 * Bean name: "validatingCouchbaseEventListener"
582
 */
583
@Bean
584
public ValidatingCouchbaseEventListener validationEventListener();
585
```
586

587
### Bean Names Constants
588

589
```java { .api }
590
/**
591
 * Standard bean name constants for Couchbase components
592
 */
593
public interface BeanNames {
594
    String COUCHBASE_TEMPLATE = "couchbaseTemplate";
595
    String REACTIVE_COUCHBASE_TEMPLATE = "reactiveCouchbaseTemplate";
596
    String COUCHBASE_MAPPING_CONTEXT = "couchbaseMappingContext";
597
    String COUCHBASE_CUSTOM_CONVERSIONS = "couchbaseCustomConversions";
598
    String COUCHBASE_OPERATIONS_MAPPING = "couchbaseOperationsMapping";
599
    String REACTIVE_COUCHBASE_OPERATIONS_MAPPING = "reactiveCouchbaseRepositoryOperationsMapping";
600
}
601
```
602

603
### Customization Interfaces
604

605
```java { .api }
606
/**
607
 * Interface for customizing cluster environment before cluster creation
608
 * Implement this interface and register as a bean to customize advanced settings
609
 */
610
@FunctionalInterface
611
public interface ClusterEnvironmentBuilderCustomizer {
612
    
613
    /**
614
     * Customize the cluster environment builder
615
     * @param builder the builder to customize
616
     */
617
    void customize(ClusterEnvironment.Builder builder);
618
}
619
```
620

621
### Custom Conversions
622

623
```java { .api }
624
/**
625
 * Interface for registering custom type conversions
626
 */
627
public class CouchbaseCustomConversions {
628
    
629
    /**
630
     * Create with custom converters for reactive operations
631
     * @param converters list of custom converters
632
     */
633
    public CouchbaseCustomConversions(List<?> converters);
634
    
635
    /**
636
     * Create with default reactive-compatible converters
637
     */
638
    public CouchbaseCustomConversions();
639
}
640

641
/**
642
 * Base interface for custom converters
643
 */
644
public interface Converter<S, T> {
645
    T convert(S source);
646
}
647
```
648

649
### Validation Support
650

651
```java { .api }
652
/**
653
 * Event listener providing JSR-303 validation for reactive operations
654
 * Automatically validates entities before save operations
655
 */
656
public class ValidatingCouchbaseEventListener {
657
    
658
    /**
659
     * Validates entity before save operations
660
     * @param source the entity being saved
661
     */
662
    @EventListener
663
    public void onBeforeSave(BeforeSaveEvent<Object> source);
664
}
665
```
666

667
## Testing Support
668

669
### Test Slice Annotation
670

671
```java { .api }
672
/**
673
 * Test annotation for Couchbase data layer testing
674
 * Configures only Couchbase-related components for fast testing
675
 */
676
@Target(ElementType.TYPE)
677
@Retention(RetentionPolicy.RUNTIME)
678
@Documented
679
@Inherited
680
@BootstrapWith(DataCouchbaseTestContextBootstrapper.class)
681
@ExtendWith(SpringExtension.class)
682
@OverrideAutoConfiguration(enabled = false)
683
@TypeExcludeFilters(DataCouchbaseTypeExcludeFilter.class)
684
@AutoConfigureCache
685
@AutoConfigureDataCouchbase
686
@AutoConfigureTestDatabase
687
@ImportAutoConfiguration
688
public @interface DataCouchbaseTest {
689
    
690
    /**
691
     * Properties to add to test environment in key=value format
692
     * @return array of key=value properties
693
     */
694
    String[] properties() default {};
695
    
696
    /**
697
     * Whether to use default filters for component scanning (default: true)
698
     * @return true to use default type filters
699
     */
700
    boolean useDefaultFilters() default true;
701
    
702
    /**
703
     * Additional include filters for component scanning
704
     * @return include filters array
705
     */
706
    Filter[] includeFilters() default {};
707
    
708
    /**
709
     * Additional exclude filters for component scanning  
710
     * @return exclude filters array
711
     */
712
    Filter[] excludeFilters() default {};
713
    
714
    /**
715
     * Auto-configuration exclusions for this test
716
     * @return classes to exclude from auto-configuration
717
     */
718
    Class<?>[] excludeAutoConfiguration() default {};
719
    
720
    /**
721
     * Component filter for fine-grained test configuration
722
     */
723
    @Target({})
724
    @Retention(RetentionPolicy.RUNTIME)
725
    @Documented
726
    @interface Filter {
727
        FilterType type() default FilterType.ANNOTATION;
728
        Class<?>[] classes() default {};
729
        String[] pattern() default {};
730
    }
731
}
732
```
733

734
### Auto-Configuration Support
735

736
```java { .api }
737
/**
738
 * Auto-configuration annotation for manual Couchbase setup in tests
739
 * Alternative to @DataCouchbaseTest for custom test configurations
740
 */
741
@Target(ElementType.TYPE)
742
@Retention(RetentionPolicy.RUNTIME)
743
@Documented
744
@ImportAutoConfiguration
745
public @interface AutoConfigureDataCouchbase {
746
}
747
```
748

749
### Test Context Customization
750

751
```java { .api }
752
/**
753
 * Test context bootstrapper for Couchbase data tests
754
 * Customizes Spring test context for Couchbase-only components
755
 */
756
public class DataCouchbaseTestContextBootstrapper extends SpringBootTestContextBootstrapper {
757
}
758

759
/**
760
 * Type exclude filter for Couchbase data tests
761
 * Excludes non-Couchbase components from test context
762
 */
763
public class DataCouchbaseTypeExcludeFilter extends AnnotationCustomizableTypeExcludeFilter {
764
}
765
```
766

767
### Test Example
768

769
```java
770
@DataCouchbaseTest
771
class UserRepositoryTest {
772
    
773
    @Autowired
774
    private TestEntityManager entityManager;
775
    
776
    @Autowired
777
    private UserRepository userRepository;
778
    
779
    @Test
780
    void shouldFindUserByEmail() {
781
        // Given
782
        User user = new User("John Doe", "john@example.com");
783
        entityManager.save(user);
784
        
785
        // When
786
        StepVerifier.create(userRepository.findByEmail("john@example.com"))
787
            // Then
788
            .expectNextMatches(found -> "John Doe".equals(found.getName()))
789
            .verifyComplete();
790
    }
791
}
792
```
793

794
## Error Handling
795

796
### Common Exceptions
797

798
```java { .api }
799
/**
800
 * Common exceptions thrown by reactive Couchbase operations
801
 */
802

803
/**
804
 * Thrown when document is not found
805
 */
806
public class DocumentNotFoundException extends CouchbaseException;
807

808
/**
809
 * Thrown when bucket is not available
810
 */
811
public class BucketNotFoundException extends CouchbaseException;
812

813
/**
814
 * Thrown on authentication failures
815
 */
816
public class AuthenticationFailureException extends CouchbaseException;
817

818
/**
819
 * Thrown on connection timeouts
820
 */
821
public class TimeoutException extends CouchbaseException;
822
```
823

824
### Reactive Error Handling
825

826
```java
827
// Handle errors in reactive chains
828
userRepository.findById("user123")
829
    .switchIfEmpty(Mono.error(new UserNotFoundException("User not found")))
830
    .onErrorResume(TimeoutException.class, ex -> 
831
        Mono.error(new ServiceUnavailableException("Database timeout")))
832
    .subscribe(
833
        user -> log.info("Found user: {}", user.getName()),
834
        error -> log.error("Error finding user", error)
835
    );
836
```
837

838
## Advanced Configuration
839

840
### Multi-Bucket Support
841

842
```java { .api }
843
/**
844
 * Configure multiple buckets by defining custom CouchbaseClientFactory beans
845
 */
846
@Configuration
847
public class MultiCouchbaseConfig {
848
    
849
    @Bean
850
    @Primary
851
    public CouchbaseClientFactory primaryBucketFactory(
852
        Cluster couchbaseCluster,
853
        CouchbaseDataProperties properties) {
854
        return new SimpleCouchbaseClientFactory(couchbaseCluster, 
855
            properties.getBucketName(), properties.getScopeName());
856
    }
857
    
858
    @Bean
859
    public CouchbaseClientFactory secondaryBucketFactory(
860
        Cluster couchbaseCluster) {
861
        return new SimpleCouchbaseClientFactory(couchbaseCluster, 
862
            "secondary-bucket", null);
863
    }
864
    
865
    @Bean
866
    public ReactiveCouchbaseTemplate secondaryTemplate(
867
        @Qualifier("secondaryBucketFactory") CouchbaseClientFactory factory,
868
        MappingCouchbaseConverter converter) {
869
        return new ReactiveCouchbaseTemplate(factory, converter);
870
    }
871
}
872
```
873

874
### Custom Field Naming Strategy
875

876
```java { .api }
877
/**
878
 * Configure custom field naming for document mapping
879
 */
880
@Configuration
881
public class CouchbaseFieldNamingConfig {
882
    
883
    @Bean
884
    public PropertyNamingStrategy fieldNamingStrategy() {
885
        return PropertyNamingStrategies.SNAKE_CASE;
886
    }
887
}
888
```
889

890
### Advanced Cluster Environment Customization
891

892
```java { .api }
893
/**
894
 * Example of advanced cluster environment customization
895
 */
896
@Configuration
897
public class CustomClusterConfig {
898
    
899
    @Bean
900
    public ClusterEnvironmentBuilderCustomizer clusterCustomizer() {
901
        return builder -> {
902
            // Custom JSON serializer
903
            builder.jsonSerializer(JacksonJsonSerializer.create());
904
            
905
            // Advanced I/O configuration
906
            builder.ioConfig(io -> io
907
                .numKvConnections(8)
908
                .networkResolution(NetworkResolution.AUTO)
909
                .enableMutationTokens(false));
910
                
911
            // Security configuration
912
            builder.securityConfig(security -> security
913
                .enableTls(true)
914
                .enableHostnameVerification(true)
915
                .trustManagerFactory(getTrustManagerFactory()));
916
                
917
            // Compression configuration  
918
            builder.compressionConfig(compression -> compression
919
                .enable(true)
920
                .minSize(32)
921
                .minRatio(0.83f));
922
        };
923
    }
924
}
925
```
926

927
## Integration Notes
928

929
### Reactive Streams Compatibility
930
- Full Project Reactor integration (Mono, Flux)
931
- RxJava reactive streams support via reactive-streams adapter  
932
- Supports backpressure and asynchronous processing
933
- Compatible with Spring WebFlux reactive web framework
934

935
### Spring Boot Integration  
936
- Auto-configuration activates when Couchbase SDK is on classpath
937
- Conditional on `spring.couchbase.connection-string` property
938
- Integrates with Spring Boot Actuator for health checks and metrics
939
- Supports Spring Boot configuration properties and profiles
940
- Compatible with Spring Boot's testing framework (@DataCouchbaseTest)
941
- Works with Spring Boot DevTools for development-time features
942

943
### Auto-Configuration Conditions
944
- **CouchbaseAutoConfiguration**: Requires `Cluster.class` and connection string
945
- **CouchbaseDataAutoConfiguration**: Requires bucket name configuration
946
- **CouchbaseReactiveDataAutoConfiguration**: Requires reactive dependencies
947
- **Repository Auto-Configuration**: Requires repository interfaces on classpath
948

949
### Performance Considerations
950
- Non-blocking I/O operations prevent thread blocking
951
- Connection pooling managed automatically with configurable min/max endpoints
952
- Configurable timeouts for different operation types (KV, query, search)
953
- Built-in clustering and failover support with automatic node discovery
954
- Document compression support for large payloads
955
- Mutation tokens for enhanced consistency guarantees
956

957
### Advanced Features
958
- **Multi-Collection Support**: Use `scopeName` property for collection-scoped operations
959
- **Auto-Indexing**: Enable `autoIndex` for automatic index creation via annotations
960
- **Custom Conversions**: Register type converters for reactive operations
961
- **Event Listeners**: JSR-303 validation and custom event handling
962
- **Field Naming Strategies**: Customize JSON field mapping (camelCase, snake_case, etc.)
963
- **Multi-Bucket Access**: Configure multiple `CouchbaseClientFactory` beans