Skip to content

docs(spring-boot): modernize Couchbase configuration and enhance error handling #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 6, 2025
Merged

docs(spring-boot): modernize Couchbase configuration and enhance error handling #65

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 88 additions & 20 deletions tutorial/markdown/java/spring-boot/spring-boot.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,41 +48,62 @@ git clone https://github.com/couchbase-examples/java-springboot-quickstart.git
### Install Dependencies

```shell
mvn package
mvn clean compile
```

> Note: Maven automatically restores packages when building the project. in IntelliJ IDEA or Eclipse depending on IDE configuration.
> Note: Maven automatically restores packages when building the project in IntelliJ IDEA or Eclipse depending on IDE configuration.

### Database Server Configuration

- The `CouchbaseConfig` class is a Spring configuration class responsible for setting up the connection to a Couchbase database in a Spring Boot application. It defines two beans:
The `CouchbaseConfig` class is a Spring configuration class responsible for setting up the connection to a Couchbase database in a Spring Boot application. It has been modernized with improved error handling and resilience:

- `getCouchbaseCluster()`: This bean creates and configures a connection to the Couchbase cluster using the provided hostname, username, and password.
- `getCouchbaseCluster()`: Creates and configures a connection to the Couchbase cluster with:
- Proper variable scoping to handle connection timeouts gracefully
- 30-second connection timeout with partial connectivity fallback
- Enhanced error logging and exception handling

- `getCouchbaseBucket(Cluster cluster)`: This bean retrieves a Couchbase bucket from a cluster, ensuring it exists and is ready within a timeout, throwing exceptions if not found or if connection times out.
- `getCouchbaseBucket(Cluster cluster)`: Retrieves a Couchbase bucket from the cluster with:
- Bucket existence validation before connection attempts
- 30-second ready timeout for improved reliability
- Comprehensive error handling for various failure scenarios

**Key Improvements**: The configuration now handles connection timeouts more gracefully and provides better error diagnostics for troubleshooting connection issues.

### Application Properties

You need to configure the connection details to your Couchbase Server in the `application.properties` file located in the `src/main/resources` directory.

In the connection string, replace `DB_CONN_STR` with the connection string of your Couchbase cluster. Replace `DB_USERNAME` and `DB_PASSWORD` with the username and password of a Couchbase user with access to the bucket.

The connection string should be in the following format:
The modern Spring Boot 3.5+ configuration uses updated property names:

```properties
spring.couchbase.bootstrap-hosts=couchbases://xyz.cloud.couchbase.com
OR
spring.couchbase.bootstrap-hosts=localhost
# Modern Couchbase configuration (Spring Boot 3.5+)
spring.couchbase.connection-string=${DB_CONN_STR}
spring.couchbase.username=${DB_USERNAME}
spring.couchbase.password=${DB_PASSWORD}
spring.couchbase.bucket.name=travel-sample

# Connection optimizations
spring.couchbase.env.timeouts.query=30000ms
spring.couchbase.env.timeouts.key-value=5000ms
spring.couchbase.env.timeouts.connect=10000ms
```

The couchbases protocol is used for secure connections.
### Environment Variables Setup

For security, use a `.env` file in your project root with your actual credentials:

```properties
spring.couchbase.bootstrap-hosts=DB_CONN_STR
spring.couchbase.bucket.user=DB_USERNAME
spring.couchbase.bucket.password=DB_PASSWORD
DB_CONN_STR=couchbases://xyz.cloud.couchbase.com
DB_USERNAME=your_username
DB_PASSWORD=your_password
```

The connection string should be in the following format:
- **Couchbase Capella**: `couchbases://xyz.cloud.couchbase.com` (secure)
- **Local Couchbase**: `couchbase://localhost` (non-secure)

The application uses the `dotenv-java` dependency to automatically load these environment variables.

For more information on the spring boot connection string, see [Common Application Properties](https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html).

## Running The Application
Expand All @@ -92,7 +113,7 @@ For more information on the spring boot connection string, see [Common Applicati
At this point the application is ready, and you can run it via your IDE or from the terminal:

```shell
mvn spring-boot:run -e -X
mvn spring-boot:run
```

> Note: Either the Couchbase Server must be installed and running on localhost or the connection string must be updated in the `application.properties` file.
Expand All @@ -108,7 +129,11 @@ docker build -t java-springboot-quickstart .
Run the Docker image

```sh
docker run -d --name springboot-container -p 8080:8080 java-springboot-quickstart -e DB_CONN_STR=<connection_string> -e DB_USERNAME=<username> -e DB_PASSWORD=<password>
docker run -d --name springboot-container -p 8080:8080 \
-e DB_CONN_STR=<connection_string> \
-e DB_USERNAME=<username> \
-e DB_PASSWORD=<password> \
java-springboot-quickstart
```

Note: The `application.properties` file has the connection information to connect to your Capella cluster. You can also pass the connection information as environment variables to the Docker container.
Expand Down Expand Up @@ -401,12 +426,44 @@ Once the query is executed, the `AirlineController` constructs an HTTP response

## Running The Tests

This command will execute all the test cases in your project.
### Integration Tests

This project uses Maven with proper integration test configuration. The tests connect to a real Couchbase instance and validate actual functionality:

```sh
mvn test
```

**Important**: This project was modernized to ensure integration tests actually execute (no false positives). The Maven surefire plugin configuration was updated to include integration tests that were previously excluded.

### Test Validation

To verify tests are actually running:
1. Tests should show connection logs to Couchbase
2. Test count should show actual execution (e.g., "Tests run: 18")
3. Any test failures will show real assertion errors

## Continuous Integration

### GitHub Actions

The project includes a modern GitHub Actions workflow (`.github/workflows/tests.yaml`) with:

- **Multiple Java Versions**: Tests on Java 17 and 21
- **Manual Triggering**: `workflow_dispatch` allows manual test runs
- **Reliability Improvements**: 15-minute timeouts, fail-fast disabled for complete results
- **Test Artifacts**: Automatic upload of test reports for debugging
- **Simplified Commands**: Uses `./mvnw clean test` for focused testing

### Running in CI/CD

The workflow automatically:
1. Sets up Java with Temurin distribution
2. Caches Maven dependencies for faster builds
3. Executes integration tests against Couchbase
4. Uploads test results as artifacts
5. Sends failure notifications to Slack (if configured)

### Run Individual Tests:

Additionally, you can run individual test classes or methods using the following commands:
Expand All @@ -431,9 +488,20 @@ mvn test -Dtest=org.couchbase.quickstart.springboot.controllers.RouteIntegration

## Project Setup Notes

This project was based on the standard [Spring Boot project](https://spring.io/guides/gs/rest-service/).
This project was based on the standard [Spring Boot project](https://spring.io/guides/gs/rest-service/) with the following specifications:

- **Spring Boot Version**: 3.5.5 (modernized from earlier versions)
- **Java Version**: 17+ (updated from Java 8)
- **Build Tool**: Maven with wrapper (`mvnw`)
- **Key Dependencies**:
- Spring Boot Starter Web
- Couchbase Java SDK 3.7.9
- Spring Boot Validation
- SpringDoc OpenAPI (Swagger)
- Dotenv Java for environment variable management
- Project Lombok for reduced boilerplate

A full list of packages are referenced in the `pom.xml` file.
A full list of packages and versions are referenced in the `pom.xml` file.

## Contributing

Expand Down
106 changes: 81 additions & 25 deletions tutorial/markdown/java/spring-data/spring-data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ length: 30 Mins

### Prerequisites

To run this prebuild project, you will need:
To run this prebuilt project, you will need:

- [Couchbase Capella](https://www.couchbase.com/products/capella/) cluster with [travel-sample](https://docs.couchbase.com/dotnet-sdk/current/ref/travel-app-data-model.html) bucket loaded.
- To run this tutorial using a self managed Couchbase cluster, please refer to the [appendix](#running-self-managed-couchbase-cluster).
Expand All @@ -35,7 +35,7 @@ To run this prebuild project, you will need:

### Source Code

The sample source code used in this tutorial is [published on GitHub](https://github.com/couchbase-examples/java-springboot-quickstart).
The sample source code used in this tutorial is [published on GitHub](https://github.com/couchbase-examples/java-springdata-quickstart).
To obtain it, clone the git repository with your IDE or execute the following command:

```shell
Expand All @@ -61,8 +61,9 @@ implementation 'org.springdoc:springdoc-openapi-ui:1.6.6'

### Database Server Configuration

Spring Data couchbase connector can be configured by providing a `@Configuration` [bean](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-definition) that extends [`AbstractCouchbaseConfiguration`](https://docs.spring.io/spring-data/couchbase/docs/current/api/org/springframework/data/couchbase/config/AbstractCouchbaseConfiguration.html).
The sample application provides a configuration bean that uses default couchbase login and password:
Spring Data Couchbase connector can be configured by providing a `@Configuration` [bean](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-definition) that extends [`AbstractCouchbaseConfiguration`](https://docs.spring.io/spring-data/couchbase/docs/current/api/org/springframework/data/couchbase/config/AbstractCouchbaseConfiguration.html).

The sample application provides a modernized configuration bean with improved error handling and environment variable support:

```java
@Slf4j
Expand Down Expand Up @@ -152,23 +153,36 @@ Please refer to [Managing Connections using the Java SDK with Couchbase Server](

You need to configure the connection details to your Couchbase Server in the application.properties file located in the src/main/resources directory.s

**Modern Spring Boot 3.5+ Configuration:**

```properties
spring.couchbase.bootstrap-hosts=DB_CONN_STR
spring.couchbase.bucket.user=DB_USERNAME
spring.couchbase.bucket.password=DB_PASSWORD
# Modern Couchbase configuration
spring.couchbase.connection-string=${DB_CONN_STR}
spring.couchbase.username=${DB_USERNAME}
spring.couchbase.password=${DB_PASSWORD}
spring.couchbase.bucket.name=travel-sample

# Connection optimizations
spring.couchbase.env.timeouts.query=30000ms
spring.couchbase.env.timeouts.key-value=5000ms
spring.couchbase.env.timeouts.connect=10000ms
```

In the connection string, replace `DB_CONN_STR` with the connection string of your Couchbase cluster. Replace `DB_USERNAME` and `DB_PASSWORD` with the username and password of a Couchbase user with access to the bucket.
### Environment Variables Setup

The connection string should be in the following format:
For security, use a `.env` file in your project root:

```properties
spring.couchbase.bootstrap-hosts=couchbases://xyz.cloud.couchbase.com
OR
spring.couchbase.bootstrap-hosts=localhost
DB_CONN_STR=couchbases://xyz.cloud.couchbase.com
DB_USERNAME=your_username
DB_PASSWORD=your_password
```

The couchbases protocol is used for secure connections. If you are using Couchbase Server 6.5 or earlier, you should use the couchbase protocol instead.
The connection string formats:
- **Couchbase Capella**: `couchbases://xyz.cloud.couchbase.com` (secure)
- **Local Couchbase**: `couchbase://localhost` (non-secure)

The `couchbases://` protocol is used for secure TLS connections (required for Couchbase Capella). The `couchbase://` protocol is for non-secure local connections.

## Running the Application

Expand All @@ -177,13 +191,13 @@ The couchbases protocol is used for secure connections. If you are using Couchba
At this point, we have installed the dependencies, loaded the travel-sample data and configured the application with the credentials. The application is now ready and you can run it.

```sh
gradle bootRun
./gradlew bootRun
```

Note: If you're using Windows, you can run the application using the `gradle.bat` executable.
Note: If you're using Windows, you can run the application using the Gradle wrapper batch file:

```sh
./gradew.bat bootRun
.\gradlew.bat bootRun
```

### Using Docker
Expand Down Expand Up @@ -362,22 +376,64 @@ For more information, see the [Couchbase Java SDK documentation](https://docs.co

## Running The Tests

To run the tests, execute `./gradlew test` (`./gradlew.bat test` on Windows).
### Integration Tests

This project uses Gradle with comprehensive integration test setup. The tests connect to a real Couchbase instance:

```sh
./gradlew test
```

**Windows users:**
```sh
.\gradlew.bat test
```

### Test Reliability

This project was modernized to ensure reliable test execution:
- Tests properly connect to Couchbase and validate real data
- Integration tests are included in the standard test run
- Test logging provides clear visibility into execution

## Continuous Integration

### GitHub Actions

The project includes a modern GitHub Actions workflow with:

- **Multi-Version Testing**: Java 17 and 21 support
- **Manual Triggering**: `workflow_dispatch` for on-demand runs
- **Enhanced Reliability**: 15-minute timeouts, non-blocking failure handling
- **Test Artifacts**: Automatic test report uploads
- **Optimized Commands**: Uses `./gradlew clean test --stacktrace`

### CI/CD Features

The workflow provides:
1. Temurin JDK setup with Gradle caching
2. Real integration test execution against Couchbase
3. Test result artifact collection for debugging
4. Slack notification integration (configurable)

## Project Setup Notes

This project was created using the [Spring Initializr](https://start.spring.io/) with the following options:
This project was created using the [Spring Initializr](https://start.spring.io/) and modernized with:

- **Project**: Gradle Project with Wrapper
- **Language**: Java
- **Spring Boot**: 3.5.5 (upgraded from 2.7.18)
- **Packaging**: Jar
- **Java Version**: 17+ (upgraded from Java 8)
- **Key Dependencies**:
- Spring Boot Starter Web
- Spring Boot Starter Data Couchbase
- SpringDoc OpenAPI Starter WebMVC UI
- Spring Boot Starter Validation
- Project Lombok
- JUnit 5 (Jupiter)

- Project: Gradle Project
- Language: Java
- Spring Boot: 2.7.18
- Packaging: Jar
- Java: 8
- Dependencies: Spring Web, Spring Data Couchbase, Springdoc OpenAPI UI
**Performance Optimizations**: The project uses `Slice` instead of `Page` for better memory efficiency and eliminates expensive `COUNT` queries in pagination scenarios.

## Contributing

Expand All @@ -399,7 +455,7 @@ If you would like to add another entity to the APIs, these are the steps to foll

If you are running this quickstart with a self managed Couchbase cluster, you need to [load](https://docs.couchbase.com/server/current/manage/manage-settings/install-sample-buckets.html) the travel-sample data bucket in your cluster and generate the credentials for the bucket.

You need to update the connection string and the credentials in the [`src/main/resources/application.properties`](https://github.com/couchbase-examples/java-springboot-quickstart/blob/main/src/main/resources/application.properties) file.
You need to update the connection string and the credentials in the [`src/main/resources/application.properties`](https://github.com/couchbase-examples/java-springdata-quickstart/blob/main/src/main/resources/application.properties) file.

> **NOTE:** Couchbase must be installed and running prior to running the Spring Boot app.

Expand Down