back to all blogsSee all blog posts

Jakarta NoSQL in Action: Switching NoSQL Databases with Ease

image of author
Maximillian Arruda on May 14, 2024
Post available in languages:

In the cloud era, switching between NoSQL solutions could be an interesting way to save resources and costs. It could also be a nightmare, especially if we’re highly coupled to a particular vendor. Certain changes could make this approach very expensive, e.g.: time spent on the change, the learning curve of a new API to use with this database, the code that will be lost, the persistence layer that needs to be replaced, etc.

This is where the flexibility of Jakarta NoSQL, with an implementation like Eclipse JNoSQL, shines.

As of March 2024, Eclipse JNoSQL supports about 30 NoSQL databases.

To explore this capability, let’s use the JNopo game introduced in blog 2 of this series.

In our scenario, let’s suppose that we need to change the JNopo’s Document NoSQL database from MongoDB, to another Document NoSQL database (Couchbase) to save money. The good thing is that because we’ve already used the Jakarta NoSQL specification to connect to our NoSQL solutions in this application, with just a few small changes we’ll be able to achieve this goal easily. Let’s take a look at the steps we need to take for this.

Configuring Eclipse JNoSQL dependencies for Couchbase

The first step we need to take is to add the Couchbase dependency to our the pom.xml file:


Configuring a local Couchbase cluster

To successfully configure our new Couchbase cluster, we’ll first need to add the following content to the docker-compose.yml file:

    image: couchbase
    container_name: couchbase-db
      - "8091-8097:8091-8097"
      - "9123:9123"
      - "11207:11207"
      - "11210:11210"
      - "11280:11280"
      - "18091-18097:18091-18097"

After we apply these changes, we then need to initialize the container by executing the following command:

docker-compose up -d

Now, let’s configure the Couchbase cluster for this example scenario:

  1. With the Couchbase container started, go to: http://localhost:8091/ui/index.html.

  2. Select the Setup New Cluster option.

    Couchbase 01
  3. Define a name for the cluster.

  4. Set root as the Admin Username.

  5. Set 123456 as the Password.

    Couchbase 02
  6. Check I accept the terms and conditions and click the Finish With Defaults button.

    Couchbase 03
  7. Go to the Buckets section.

  8. Create a jnopo Bucket by clicking on the Add Bucket option

    Couchbase 04
  9. Click Scopes & Collections and then click Add Collection.

  10. Enter GameMatch as the collection name and click the Save button to complete your creation.

    Couchbase 05
  11. Now, in the Query Editor section, run the command N1QL command to create the primary index for the GameMatch collection:

    CREATE PRIMARY INDEX primaryGameMatch ON jnopo._default.GameMatch
    Couchbase 06

With a Couchbase cluster running, we just need to set up Eclipse JNoSQL to connect to it.

Apply the following changes into the resources/META-INF/ file:

## Couchbase

The jnosql.document.provider property is required in this context because we have more than one Eclipse JNoSQL Database API for Document NoSQL implementations. You can learn more about the configurations available for Eclipse JNoSQL Database API for Couchbase in this Git repository.

That’s all! Let’s restart the Open Liberty runtime to make sure that everything is running smoothly:

  • On Linux/Mac machines, run the following command:

    ./mvnw liberty:dev
  • On Windows machines, run the following command:

    mvnw.cmd liberty:dev

After some game matches, you should see something similar to the following images to prove that this data is now being stored in our new Couchbase database.

Couchbase Verification 01
Couchbase Verification 02

If you’re interesting to take a look on the finished project code developed during this challenge, clone this Git repository and navigate to the database-switching-challenge directory.

git clone
cd sample-jakartaNoSQL-game
cd database-switching-challenge

Key takeaways

This blog has shown just how easy it can be to switch between NoSQL solutions by using Jakarta NoSQL, bringing one more item to your utility belt that could be useful in helping you save resources and costs.

By reading this blog, you should now be familiar with:

  • How to set up the Couchbase database cluster for development purposes;

  • How to switch between NoSQL database from different vendors, in our example: switching from MongoDB to Couchbase;

Next steps: continuing the journey

Congratulations on getting this far!

This blog post is the 3rd part of a set of blog posts:

To see more sample projects, take a look at the official Eclipse JNoSQL samples repositories:

To learn more about Eclipse JNoSQL, take a look at these official repositories:

if you’re an expert on some NoSQL database that Eclipse JNoSQL doesn’t support, feel free to open an issue or a PR on the project repositories mentioned above. Except for the NoSQL solutions mentioned like MongoDB and Couchbase, all the technology used in this blog post are open-source, so, what do you think about contributing to these projects? If you don’t know how to get started to contribute, take a look at this Coffee.withJava("Contribute to JNoSQL") Youtube Series, or if you prefer, feel free to contact me! Contributing to these projects is not just with codes, you could help a lot by promoting and speaking about them wherever you go! Contributing to open-source is a great way to boost your career, and improve your skills to become an effective developer and relevant in the market! Think about that!

Special thanks

I’m bursting with gratitude and would love to give a big shout-out to my incredible Java community friends for their unwavering support throughout my journey. A special round of applause for:

  • Otavio Santana, you’re not just a mentor but a guiding star in my open-source journey. Your mentorship have opened doors for me to become an active open-source contributor and a proud Eclipse Foundation committer. Thank you for being such a monumental part of my journey. Also, thanks for your insightful reviews of the codes featured in this blog post.

  • Karina Varela, your keen eye for detail and your generosity in sharing your knowledge have enriched this content beyond measure. Your thoughtful reviews have made this content not just better, but truly curated and relevant. I’m so grateful for your contribution.

  • Gabriel Silva Andrade, your support and encouragement have been a constant source of inspiration for me. Your partnership at the SouJava JUG and Java community initiatives around this subject have been invaluable in shaping this content. Thank you for your unwavering support.

  • Fabio Franco, you were the catalyst for this wonderful opportunity, connecting me with the fantastic OpenLiberty team and offering your support throughout the publishing process of this blog post. Your belief in me and your encouragement have been invaluable. Thank you for making this possible.

  • And to the OpenLiberty team, thank you for opening your doors and allowing me the privilege to share and post this content that I’ve thoroughly enjoyed working on. Thanks for this opportunity.

To each of you, your support means a lot to me, and I’m deeply thankful.