{"id":45157405,"url":"https://github.com/couchbase-examples/java-springdata-quickstart","last_synced_at":"2026-02-20T05:02:38.307Z","repository":{"id":38457816,"uuid":"470787918","full_name":"couchbase-examples/java-springdata-quickstart","owner":"couchbase-examples","description":"Example Spring Data Couchbase application","archived":false,"fork":false,"pushed_at":"2026-01-30T10:33:44.000Z","size":1611,"stargazers_count":1,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-01-31T02:49:22.732Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/couchbase-examples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-03-16T23:52:22.000Z","updated_at":"2026-01-30T10:33:42.000Z","dependencies_parsed_at":"2023-12-13T09:02:47.351Z","dependency_job_id":"81f05baf-03bb-47df-b545-340e919b27d0","html_url":"https://github.com/couchbase-examples/java-springdata-quickstart","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/couchbase-examples/java-springdata-quickstart","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fjava-springdata-quickstart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fjava-springdata-quickstart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fjava-springdata-quickstart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fjava-springdata-quickstart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/couchbase-examples","download_url":"https://codeload.github.com/couchbase-examples/java-springdata-quickstart/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase-examples%2Fjava-springdata-quickstart/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29641929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T03:21:14.183Z","status":"ssl_error","status_checked_at":"2026-02-20T03:18:24.455Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-20T05:02:35.821Z","updated_at":"2026-02-20T05:02:38.299Z","avatar_url":"https://github.com/couchbase-examples.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quickstart in Couchbase with Spring Data and Java\n\n#### REST API using Couchbase Capella in Java using Spring Data\n\nOften, the first step developers take after creating their database is to create a REST API that can perform Create, Read, Update, and Delete (CRUD) operations for that database. This repo is designed to teach you and give you a starter project (in Java using Spring Data) to generate such a REST API. After you have installed the travel-sample bucket in your database, you can run this application which is a REST API with Swagger documentation so that you can learn:\n\n1. How to create, read, update, and delete documents using Key-Value[ operations](https://docs.couchbase.com/java-sdk/current/howtos/kv-operations.html) (KV operations). KV operations are unique to Couchbase and provide super fast (think microseconds) queries.\n2. How to write simple parameterized [SQL++ Queries](https://docs.couchbase.com/java-sdk/current/howtos/n1ql-queries-with-sdk.html) using the built-in travel-sample bucket.\n\nFull documentation for the tutorial can be found on the [Couchbase Developer Portal](https://developer.couchbase.com/tutorial-quickstart-spring-data-java/).\n\nThis example uses spring data, however, if you are looking for springboot sample app please go to this [repository](https://github.com/couchbase-examples/java-springboot-quickstart).\n\n## Prerequisites\n\nTo run this prebuilt project, you will need:\n\n- [Couchbase Capella](https://www.couchbase.com/products/capella/) cluster with [travel-sample](https://docs.couchbase.com/java-sdk/current/ref/travel-app-data-model.html) bucket loaded.\n  - To run this tutorial using a self-managed Couchbase cluster, please refer to the [appendix](#running-self-managed-couchbase-cluster).\n- [Java 17 or higher](https://www.oracle.com/in/java/technologies/downloads/#java17)\n  - **Java 17+ is required** for Gradle 9.0+ compatibility\n  - Ensure that the Java version is compatible with the Couchbase SDK\n- [Loading Travel Sample Bucket](https://docs.couchbase.com/cloud/clusters/data-service/import-data-documents.html#import-sample-data)\n  - If `travel-sample` is not loaded in your Capella cluster, you can load it by following the instructions for your Capella Cluster\n- [Gradle 9.0 or higher](https://gradle.org/releases/)\n  - The project uses Gradle wrapper, so manual installation is optional\n\n## App Setup\n\nWe will walk through the different steps required to get the application running.\n\n### Cloning Repo\n\n```shell\ngit clone https://github.com/couchbase-examples/java-springdata-quickstart.git\n```\n\n### Install Dependencies\n\nThe dependencies for the application are specified in the `build.gradle` file in the source folder. Dependencies can be installed through `gradle` the default package manager for Java.\n\n```\n./gradlew build -x test\n```\n\nNote: The `-x test` option is used to skip the tests. The tests require the application to be running.\n\nNote: The application is tested with Java 17. If you are using a different version of Java, please update the `build.gradle` file accordingly.\n\n### Setup Database Configuration\n\nTo learn more about connecting to your Capella cluster, please follow the [instructions](https://docs.couchbase.com/cloud/get-started/connect.html).\n\nSpecifically, you need to do the following:\n\n- Create the [database credentials](https://docs.couchbase.com/cloud/clusters/manage-database-users.html) to access the travel-sample bucket (Read and Write) used in the application.\n- [Allow access](https://docs.couchbase.com/cloud/clusters/allow-ip-address.html) to the Cluster from the IP on which the application is running.\n\nAll configuration for communication with the database is read from environment variables. This quickstart provides two convenient ways to set up your database connection:\n\n### Option 1: Environment Variables (Recommended for Production)\n\nSet the environment variables directly in your environment:\n\n```sh\nexport DB_CONN_STR=couchbases://\u003ccluster-url\u003e\nexport DB_USERNAME=your-username\nexport DB_PASSWORD=your-password\n```\n\n### Option 2: .env File (Recommended for Local Development)\n\nCreate a `.env` file in the project root directory:\n\n```env\n# Copy from .env.example and update with your actual values\nDB_CONN_STR=couchbases://your-cluster-url.cloud.couchbase.com\nDB_USERNAME=your-username\nDB_PASSWORD=your-password\n```\n\nThe `application.properties` file uses these environment variables with modern Spring Boot 4.0+ properties:\n\n```properties\n# Server configuration\nserver.forward-headers-strategy=framework\n\n# Modern Couchbase configuration (Spring Boot 4.0+)\nspring.couchbase.connection-string=${DB_CONN_STR}\nspring.couchbase.username=${DB_USERNAME}\nspring.couchbase.password=${DB_PASSWORD}\n\n# Couchbase connection optimizations\nspring.couchbase.env.timeouts.query=30000ms\nspring.couchbase.env.timeouts.key-value=5000ms\nspring.couchbase.env.timeouts.connect=10000ms\n```\n\nThe application automatically loads environment variables from the `.env` file for local development convenience.\n\n\u003e Note: The connection string expects the `couchbases://` or `couchbase://` part.\n\n## Cluster Connection Configuration\n\nYou do not need to make any changes to your configuration for this quickstart. However, read this section if you want to learn more about how 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).\n\n```java\n@Slf4j\n@Configuration\n@EnableCouchbaseRepositories\npublic class CouchbaseConfiguration extends AbstractCouchbaseConfiguration {\n\n  @Value(\"#{systemEnvironment['DB_CONN_STR'] ?: '${spring.couchbase.connection-string:localhost}'}\")\n  private String host;\n\n  @Value(\"#{systemEnvironment['DB_USERNAME'] ?: '${spring.couchbase.username:Administrator}'}\")\n  private String username;\n\n  @Value(\"#{systemEnvironment['DB_PASSWORD'] ?: '${spring.couchbase.password:password}'}\")\n  private String password;\n\n  // Since bucket auto-configuration is removed in modern Spring Boot, we hardcode the bucket name\n  private String bucketName = \"travel-sample\";\n\n  @Override\n  public String getConnectionString() {\n    return host;\n  }\n\n  @Override\n  public String getUserName() {\n    return username;\n  }\n\n  @Override\n  public String getPassword() {\n    return password;\n  }\n\n  @Override\n  public String getBucketName() {\n    return bucketName;\n  }\n\n  @Override\n  public String typeKey() {\n    return \"type\";\n  }\n\n  @Override\n  @Bean(destroyMethod = \"disconnect\")\n  public Cluster couchbaseCluster(ClusterEnvironment couchbaseClusterEnvironment) {\n    try {\n      log.debug(\"Connecting to Couchbase cluster at \" + host);\n      return Cluster.connect(getConnectionString(), getUserName(), getPassword());\n    } catch (Exception e) {\n      log.error(\"Error connecting to Couchbase cluster\", e);\n      throw e;\n    }\n  }\n\n  @Bean\n  public Bucket getCouchbaseBucket(Cluster cluster) {\n    try {\n      if (!cluster.buckets().getAllBuckets().containsKey(getBucketName())) {\n        log.error(\"Bucket with name {} does not exist. Creating it now\", getBucketName());\n        throw new BucketNotFoundException(bucketName);\n      }\n      return cluster.bucket(getBucketName());\n    } catch (Exception e) {\n      log.error(\"Error getting bucket\", e);\n      throw e;\n    }\n  }\n\n}\n```\n\n\u003e _from config/CouchbaseConfiguration.java_\n\nThis configuration uses modern Spring Boot 4.0+ properties and automatically loads environment variables from `.env` files for local development. The configuration assumes you have either a locally running Couchbase server or a Couchbase Capella cluster.\n\nApplications deployed to production or staging environments should use less privileged credentials created using [Role-Based Access Control](https://docs.couchbase.com/go-sdk/current/concept-docs/rbac.html).\nPlease refer to [Managing Connections using the Java SDK with Couchbase Server](https://docs.couchbase.com/java-sdk/current/howtos/managing-connections.html) for more information on Capella and local cluster connections.\n\n## Running The Application\n\n### Directly on Machine\n\nAt 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.\n\n```sh\n./gradlew bootRun\n```\n\nNote: If you're using Windows, you can run the application using the Gradle wrapper batch file.\n\n```sh\n./gradlew.bat bootRun\n```\n\n### Using Docker\n\nBuild the Docker image\n\n```sh\ndocker build -t java-springdata-quickstart .\n```\n\nRun the Docker image\n\n```sh\ndocker run -d --name springdata-container -p 8080:8080 \\\n  -e DB_CONN_STR=couchbases://your-cluster-url.cloud.couchbase.com \\\n  -e DB_USERNAME=your-username \\\n  -e DB_PASSWORD=your-password \\\n  java-springdata-quickstart\n```\n\nNote: Pass your database credentials as environment variables to the Docker container. The `.env` file is used only for local development and won't be available in Docker containers.\n\n### Verifying the Application\n\nOnce the application starts, you can see the details of the application on the logs.\n\n![Application Startup](./assets/images/app-startup-spring-data.png)\n\nThe application will run on port 8080 of your local machine (http://localhost:8080). You will find the interactive Swagger documentation of the API if you go to the URL in your browser. Swagger documentation is used in this demo to showcase the different API endpoints and how they can be invoked. More details on the Swagger documentation can be found in the [appendix](#swagger-documentation).\n\n![Swagger Documentation](./assets/images/swagger-documentation-spring-data.png)\n\n## Running Tests\n\nTo run the integration tests, use the following commands:\n\n```sh\n./gradlew test\n```\n\nNote: The tests include comprehensive integration tests that connect to your Couchbase cluster and validate all CRUD operations with clean logging output.\n\n## Appendix\n\n### Data Model\n\nFor this quickstart, we use three collections, `airport`, `airline` and `routes` that contain sample airports, airlines and airline routes respectively. The routes 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.\n\n![travel-sample data model](./assets/images/travel_sample_data_model.png)\n\n### Extending API by Adding New Entity\n\nIf you would like to add another entity to the APIs, these are the steps to follow:\n\n- You can create the collection using the [SDK](https://docs.couchbase.com/sdk-api/couchbase-java-client-3.5.2/com/couchbase/client/java/Collection.html#createScope-java.lang.String-) or via the [Couchbase Server interface](https://docs.couchbase.com/cloud/n1ql/n1ql-language-reference/createcollection.html).\n- Create a new entity class in the `models` package similar to the existing entity classes like `Airport.java`.\n- Define the controller in a new file in the `controllers` folder similar to the existing classes like `AirportController.java`.\n- Define the service in a new file in the `services` folder similar to the existing classes like `AirportService.java`.\n- Define the repository in a new file in the `repositories` folder similar to the existing classes like `AirportRepository.java`.\n\n### Running Self-Managed Couchbase Cluster\n\nIf 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.\n\nYou need to update the connection string and the credentials in the `application.properties` file in the `src/main/resources` folder.\n\nNote: Couchbase Server version 7 or higher must be installed and running before running the Spring Boot Java app.\n\n### Swagger Documentation\n\nSwagger documentation provides a clear view of the API including endpoints, HTTP methods, request parameters, and response objects.\n\nClick 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.\n\n#### Trying Out the API\n\nYou can try out an API by clicking on the \"Try it out\" button next to the endpoints.\n\n- 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.\n\n- 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.\n\n#### Models\n\nSwagger 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Fjava-springdata-quickstart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcouchbase-examples%2Fjava-springdata-quickstart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase-examples%2Fjava-springdata-quickstart/lists"}