Quickstart in Couchbase with Java and Spring Boot

Getting Started

Prerequisites

To run this prebuilt project, you will need:

• Couchbase Capella cluster with travel-sample bucket loaded.
  • To run this tutorial using a self managed Couchbase cluster, please refer to the appendix.
• Java SDK 17 or higher installed
• Code Editor installed (IntelliJ IDEA, Eclipse, or Visual Studio Code)
• Maven command line

Source Code

git clone https://github.com/couchbase-examples/java-springboot-quickstart.git

Install Dependencies

mvn clean compile

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 has been modernized with improved error handling and resilience:

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

The modern Spring Boot 3.5+ configuration uses updated property names:

# 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

Environment Variables Setup

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

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.

Running The Application

Directly on the machine

At this point the application is ready, and you can run it via your IDE or from the terminal:

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.

Docker

Build the Docker image

docker build -t java-springboot-quickstart .

Run the Docker image

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. If you choose not to pass the environment variables, you can update the application.properties file in the src/main/resources folder.

Once the application is running, you can see the logs in the console. You should see the following log message indicating that the application has started successfully:

Once the site is up and running you can launch your browser and go to the Swagger Start Page to test the APIs.

Data Model

For this tutorial, we use three collections, airport, airline and route that contain sample airports, airlines and airline routes respectively. The route collection connects the airports and airlines as seen in the figure below. We use these connections in the quickstart to generate airports that are directly connected and airlines connecting to a destination airport. Note that these are just examples to highlight how you can use SQL++ queries to join the collections.

Airline Document Structure

We will be setting up a REST API to manage some airline documents. The name field is the name of the airline. The callsign field is the callsign of the airline. The iata field is the IATA code of the airline. The icao field is the ICAO code of the airline. The country field is the country of the airline.

Our airline document will have a structure similar to the following example:

{
  "name": "Couchbase Airways",
  "callsign": "Couchbase",
  "iata": "CB",
  "icao": "CBA",
  "country": "United States"
}

Let's Review the Code

To begin open the repository in an IDE of your choice to learn about how to create, read, update and delete documents in your Couchbase Server.

Code Organization

• src/test/java: Contains integration tests.
• src/main/java/org/couchbase/quickstart/springboot/repositories: Contains the repository implementation.
• src/main/java/org/couchbase/quickstart/springboot/models: Contains the data model.
• src/main/java/org/couchbase/quickstart/springboot/controllers: Contains the RESTful API controllers.
• src/main/java/org/couchbase/quickstart/springboot/services: Contains the service classes.

Model

Airline.java This class represents the data model for an airline. It contains fields such as ID, type, name, IATA code, ICAO code, callsign, and country. The class uses annotations for validation.

Controller

AirlineController.java This class defines the RESTful API endpoints for managing airlines. It handles HTTP requests for creating, updating, deleting, and retrieving airlines. It also provides endpoints for listing airlines by various criteria.

An example of the pattern for the GET mapping is shown below.For the full code, see the AirlineController.java.

@RestController
@RequestMapping("/api/v1/airline")
@Slf4j
public class AirlineController {

   private final AirlineService airlineService;

    public AirlineController(AirlineService airlineService) {
        this.airlineService = airlineService;
    }

    // Error messages
    private static final String INTERNAL_SERVER_ERROR = "Internal Server Error";
    private static final String DOCUMENT_NOT_FOUND = "Document Not Found";

    @GetMapping("/{id}")
    @Operation(summary = "Get an airline by ID")
    @Description(value = "...")
    public ResponseEntity<Airline> getAirline(@PathVariable String id) {
        try {
            Airline airline = airlineService.getAirlineById(id);
            if (airline != null) {
                return new ResponseEntity<>(airline, HttpStatus.OK);
            } else {
                log.error(DOCUMENT_NOT_FOUND + ": " + id);
                return new ResponseEntity<>(HttpStatus.NOT_FOUND);
            }
        } catch (DocumentNotFoundException e) {
            log.error(DOCUMENT_NOT_FOUND + ": " + id);
            return new ResponseEntity<>(HttpStatus.NOT_FOUND);
        } catch (Exception e) {
            log.error(INTERNAL_SERVER_ERROR + ": " + e.getMessage());
            return new ResponseEntity<>(HttpStatus.INTERNAL_SERVER_ERROR);
        }
    }
}

Service

AirlineServiceImpl.java This class implements the AirlineService interface. It acts as an intermediary between the controller and repository, providing business logic for managing airlines.

An example of the pattern for AirlineService is shown below. For the full code, see the AirlineServiceImpl.java.

public interface AirlineService {

    Airline getAirlineById(String id);

    ...
}

@Service
public class AirlineServiceImpl implements AirlineService {

    private final AirlineRepository airlineRepository;

    public AirlineServiceImpl(AirlineRepository airlineRepository) {
        this.airlineRepository = airlineRepository;
    }

    @Override
    public Airline getAirlineById(String id) {
        return airlineRepository.findById(id);
    }

    ...
}

Repository

AirlineRepositoryImpl.java This class implements the AirlineRepository interface. It interacts with the Couchbase database to perform CRUD operations on airline documents. It uses the Couchbase Java SDK to execute queries and operations.

An example of the pattern for AirlineRepository is shown below. For the full code, see the AirlineRepositoryImpl.java.

public interface AirlineRepository {

    Airline findById(String id);

    ...
}

@Repository
public class AirlineRepositoryImpl implements AirlineRepository {

    private final Cluster cluster;
    private final Collection airlineCol;
    private final CouchbaseConfig couchbaseConfig;

    public AirlineRepositoryImpl(Cluster cluster, Bucket bucket, CouchbaseConfig couchbaseConfig) {
        this.cluster = cluster;
        this.airlineCol = bucket.scope("inventory").collection("airline");
        this.couchbaseConfig = couchbaseConfig;
    }

    @Override
    public Airline findById(String id) {
        return airlineCol.get(id).contentAs(Airline.class);
    }

    ...
}

Mapping Workflow

Mapping workflows describe how the HTTP methods (GET, POST, PUT, DELETE) interact with the AirlineService and the underlying database through the AirlineRepository to perform various operations on airline data.

A simple REST API using Spring Boot and the Couchbase SDK version 3.x with the following endpoints:

• Retrieve airlines by ID.
• Create new airlines with essential information.
• Update airline details.
• Delete airlines.
• List all airlines with pagination.
• List airlines by country and destination airport.

GET Mapping Workflow

@GetMapping("/{id}")

The GET mapping is triggered when a client sends an HTTP GET request to /api/v1/airline/{id} where {id} is the unique identifier of the airline.

1. The AirlineController receives the request and extracts the id from the URL path.
2. It then calls the getAirlineById method of the AirlineService, passing the extracted id as a parameter.This function internally calls get() to retrieve the airline from the database.
3. The AirlineService interacts with the database through the AirlineRepository to find the airline with the specified id.
4. If the airline is found, the AirlineService returns it as a response.
5. The AirlineController constructs an HTTP response with a status code of 200 OK and includes the airline data in the response body as a JSON object.
6. The response is sent back to the client with the airline data if found, or a 404 Not Found response if the airline does not exist.

POST Mapping Workflow

@PostMapping("/{id}")

The POST mapping is triggered when a client sends an HTTP POST request to /api/v1/airline/{id}, where {id} is typically a unique identifier generated by the server (not provided by the client).

1. The client includes the data of the new airline to be created in the request body as a JSON object.
2. The AirlineController receives the request and extracts the id from the URL path, but this id is not used for creating the airline; it's often generated by the server.
3. The AirlineController calls the createAirline method of the AirlineService, passing the airline data from the request body. This function internally calls airlineCol.insert() to insert the airline into the database.
4. The AirlineService is responsible for creating a new airline and saving it to the database using the AirlineRepository.
5. If the airline is created successfully, the AirlineService returns the newly created airline.
6. The AirlineController constructs an HTTP response with a status code of 201 Created and includes the created airline data in the response body as a JSON object.
7. The response is sent back to the client with the newly created airline data.

PUT Mapping Workflow

@PutMapping("/{id}")

The PUT mapping is triggered when a client sends an HTTP PUT request to /api/v1/airline/{id}, where {id} is the unique identifier of the airline to be updated.

1. The client includes the updated data of the airline in the request body as a JSON object.
2. The AirlineController receives the request, extracts the id from the URL path, and retrieves the updated airline data from the request body.
3. The AirlineController calls the updateAirline method of the AirlineService, passing the id and updated airline data. This function internally calls airlineCol.replace() to replace the airline in the database.
4. The AirlineService is responsible for updating the airline in the database using the AirlineRepository.
5. If the airline is updated successfully, the AirlineService returns the updated airline.
6. The AirlineController constructs an HTTP response with a status code of 200 OK and includes the updated airline data in the response body as a JSON object.
7. The response is sent back to the client with the updated airline data if found, or a 404 Not Found response if the airline with the specified ID does not exist.

DELETE Mapping Workflow

@DeleteMapping("/{id}")

The DELETE mapping is triggered when a client sends an HTTP DELETE request to /api/v1/airline/{id}, where {id} is the unique identifier of the airline to be deleted.

1. The AirlineController receives the request and extracts the id from the URL path.
2. The AirlineController calls the deleteAirline method of the AirlineService, passing the id of the airline to be deleted. This function internally calls airlineCol.remove() to remove the airline from the database.
3. The AirlineService is responsible for deleting the airline from the database using the AirlineRepository.
4. If the airline is deleted successfully, the AirlineService performs the deletion operation without returning any response data.
5. The AirlineController constructs an HTTP response with a status code of 204 No Content, indicating that the request was successful, but there is no content to return in the response body.
6. The response is sent back to the client to indicate the successful deletion of the airline.

These workflows illustrate how each HTTP method interacts with the AirlineService and the underlying database through the AirlineRepository to perform various operations on airline data.

Custom SQL++ Queries

1. Get all airlines by country

 @Override
    public List<Airline> findByCountry(String country, int limit, int offset) {
        String statement = "SELECT airline.id, airline.type, airline.name, airline.iata, airline.icao, airline.callsign, airline.country FROM `"
                + couchbaseConfig.getBucketName() + "`.`inventory`.`airline` WHERE country = $1 LIMIT $2 OFFSET $3";
        return cluster
                .query(statement,
                        QueryOptions.queryOptions().parameters(JsonArray.from(country, limit, offset))
                                .scanConsistency(QueryScanConsistency.REQUEST_PLUS))
                .rowsAs(Airline.class);
  }

In the above example, we are using the QueryOptions class to set the scanConsistency to REQUEST_PLUS to ensure that the query returns the latest data. We are also using the JsonObject class to set the country parameter in the query. For more information on query options and scan consistency, you can refer to the Query Options and Scan Consistency documentation.

Finally, we are using the rowsAs method to return the query results as a list of Airline objects.

In the query, we are using the country parameter to filter the results by country. We are also using the limit and offset parameters to limit the number of results returned and to implement pagination.

Once the query is executed, the AirlineController constructs an HTTP response with a status code of 200 OK and includes the list of airlines in the response body as a list of JSON objects.

2. Get all airlines by destination airport

 @Override
    public List<Airline> findByDestinationAirport(String destinationAirport, int limit, int offset) {
        String statement = "SELECT air.callsign, air.country, air.iata, air.icao, air.id, air.name, air.type " +
                "FROM (SELECT DISTINCT META(airline).id AS airlineId " +
                "      FROM `" + couchbaseConfig.getBucketName() + "`.`inventory`.`route` " +
                "      JOIN `" + couchbaseConfig.getBucketName() + "`.`inventory`.`airline` " +
                "      ON route.airlineid = META(airline).id " +
                "      WHERE route.destinationairport = $1) AS subquery " +
                "JOIN `" + couchbaseConfig.getBucketName() + "`.`inventory`.`airline` AS air " +
                "ON META(air).id = subquery.airlineId LIMIT $2 OFFSET $3";

        return ...
  }

In the query, we are using the destinationAirport parameter to filter the results by destination airport. We are also using the limit and offset parameters to limit the number of results returned and to implement pagination.

We are performing a JOIN operation between the route and airline documents to get the airlines that fly to the specified destination airport. We are using the META function to get the ID of the airline document.

Once the query is executed, the AirlineController constructs an HTTP response with a status code of 200 OK and includes the list of airlines in the response body as a list of JSON objects.

Running The Tests

Integration Tests

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

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:

To run the tests for the AirlineIntegrationTest class:

mvn test -Dtest=org.couchbase.quickstart.springboot.controllers.AirlineIntegrationTest

To run the tests for the AirportIntegrationTest class:

mvn test -Dtest=org.couchbase.quickstart.springboot.controllers.AirportIntegrationTest

To run the tests for the RouteIntegrationTest class:

mvn test -Dtest=org.couchbase.quickstart.springboot.controllers.RouteIntegrationTest

Project Setup Notes

This project was based on the standard Spring Boot project 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 and versions are referenced in the pom.xml file.

Contributing

Contributions are welcome! If you'd like to contribute to this project, please fork the repository and create a pull request.

Appendix

Extending API by Adding New Entity

If you would like to add another entity to the APIs, these are the steps to follow:

• Create the new entity (collection) in the Couchbase bucket. You can create the collection using the SDK or via the Couchbase Server interface.
• Define the routes in a new class in the controllers package similar to the existing routes like AirportController.java.
• Define the service in a new class in the services package similar to the existing services like AirportService.java.
• Define the repository in a new class in the repositories package similar to the existing repositories like AirportRepository.java.
• For integration tests, create a new class in the controllers package similar to the existing tests like AirportIntegrationTest.java.

Running Self Managed Couchbase Cluster

If you are running this quickstart with a self managed Couchbase cluster, you need to load 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 file.

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

Swagger Documentation

Swagger documentation provides a clear view of the API including endpoints, HTTP methods, request parameters, and response objects.

Click on an individual endpoint to expand it and see detailed information. This includes the endpoint's description, possible response status codes, and the request parameters it accepts.

Trying Out the API

You can try out an API by clicking on the "Try it out" button next to the endpoints.

• Parameters: If an endpoint requires parameters, Swagger UI provides input boxes for you to fill in. This could include path parameters, query strings, headers, or the body of a POST/PUT request.

• Execution: Once you've inputted all the necessary parameters, you can click the "Execute" button to make a live API call. Swagger UI will send the request to the API and display the response directly in the documentation. This includes the response code, response headers, and response body.

Models

Swagger documents the structure of request and response bodies using models. These models define the expected data structure using JSON schema and are extremely helpful in understanding what data to send and expect.