Harness the Power of Quarkus and HarperDB for Efficient Data Management

In the ever-evolving landscape of database technology, staying ahead of the curve is not just an option, it’s a necessity. As modern applications continue to grow in complexity and global reach, the role of the underlying database becomes increasingly critical. It’s the backbone that supports the seamless functioning of applications and the storage and retrieval of vast amounts of data. In this era of global-scale applications, having a high-performance, flexible, and efficient database is paramount.

As the demands of modern applications surge, the need for a database that can keep pace has never been greater. The “ultra-database” has become a key player in ensuring that applications run seamlessly and efficiently globally. These databases need to offer a unique combination of speed, versatility, and adaptability to meet the diverse requirements of various applications, from e-commerce platforms to IoT systems.

They need to be more than just data repositories. They must serve as intelligent hubs that can quickly process, store, and serve data while facilitating real-time analytics, security, and scalability. The ideal ultra-database is not just a storage facility; it’s an engine that drives the dynamic, data-driven applications that define the modern digital landscape.

The latest release of HarperDB 4.2 introduces a unified development architecture for enterprise applications, providing an approach to building global-scale applications.

HarperDB 4.2

HarperDB 4.2 is a comprehensive solution that seamlessly combines an ultra-fast database, user-programmable applications, and data streaming into a cohesive technology. The result is a development environment that simplifies the complex, accelerates the slow, and reduces costs. HarperDB 4.2 offers a unified platform that empowers developers to create applications that can span the globe, handling data easily and quickly.

In this tutorial, we will explore the features of HarperDB 4.2 and show you how to harness its power in conjunction with Java Quarkus. We will take you through the steps to leverage HarperDB’s new capabilities to build robust and high-performance applications with Quarkus, demonstrating the impressive potential of this unified development architecture. So, join us on this enlightening journey and revolutionize your application development process.

Creating a Quarkus Microservice API With HarperDB, Part 1: Setting up the Environment

This section will guide you through configuring your development environment and creating the necessary project setup to get started.

Step 1: Configuring the Environment

Before diving into the development, you need to set up your environment. We’ll start by running HarperDB in a Docker container.

To do this, open your terminal and run the following command:

docker run -d   -e HDB_ADMIN_USERNAME=root   -e HDB_ADMIN_PASSWORD=password   -e HTTP_THREADS=4  -p 9925:9925   -p 9926:9926 harperdb/harperdb

This command downloads and runs the HarperDB Docker container with the specified configuration. It exposes the necessary ports for communication.

Step 2: Creating a Schema and Table

With HarperDB up and running, the next step is to create a schema and define a table to store animal data. We will use the “curl” commands to interact with HarperDB’s RESTful API.

1. Create a schema named “dev” by executing the following command:

curl --location --request POST 'http://localhost:9925/' \
--header 'Authorization: Basic cm9vdDpwYXNzd29yZA==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "operation": "create_schema",
    "schema": "dev"
}'

This command sends a POST request to create the “dev” schema.

2. Next, create a table named “animal” with “scientificName” as the hash attribute using the following command:

curl --location 'http://localhost:9925' \
--header 'Authorization: Basic cm9vdDpwYXNzd29yZA==' \
--header 'Content-Type: application/json' \
--data '{
    "operation": "create_table",
    "schema": "dev",
    "table": "animal",
    "hash_attribute": "scientificName"
}'

This command establishes the “animal” table within the “dev” schema.

3. Now, add the required attributes for the “animal” table by creating “name,” “genus,” and “species” attributes:

curl --location 'http://localhost:9925' \
--header 'Authorization: Basic cm9vdDpwYXNzd29yZA==' \
--header 'Content-Type: application/json' \
--data '{
    "operation": "create_attribute",
    "schema": "dev",
    "table": "animal",
    "attribute": "name"
}'

curl --location 'http://localhost:9925' \
--header 'Authorization: Basic cm9vdDpwYXNzd29yZA==' \
--header 'Content-Type: application/json' \
--data '{
    "operation": "create_attribute",
    "schema": "dev",
    "table": "animal",
    "attribute": "genus"
}'

curl --location 'http://localhost:9925' \
--header 'Authorization: Basic cm9vdDpwYXNzd29yZA==' \
--header 'Content-Type: application/json' \
--data '{
    "operation": "create_attribute",
    "schema": "dev",
    "table": "animal",
    "attribute": "species"
}'

These commands add the “name”, “genus”, and “species” attributes to the “animal” table within the “dev” schema.

With HarperDB configured and the schema and table set up, you can start building your Quarkus-based microservice API to manage animal data. Stay tuned for the next part of the tutorial, where we’ll dive into the development process.

Building Quarkus Application

We configured HarperDB and prepared the environment. Now, we’ll start building our Quarkus application to manage animal data. Quarkus makes it easy with a handy project generator, so let’s begin.

Quarkus offers an intuitive web-based project generator that simplifies the initial setup. Visit Quarkus Project Generator, and follow these steps:

1. Select the extensions you need for your project. Add “JAX-RS” and “JSON” for this tutorial to handle REST endpoints and JSON serialization.
2. Click the “Generate your application” button.
3. Download the generated ZIP file and extract it to your desired project directory.

With your Quarkus project generated, you’re ready to move on.

Our project will use the DataFaker library and the HarperDB Java driver to generate animal data to interact with the HarperDB database. To include the HarperDB Java Driver, please read the previous article.

In your Quarkus project, create a Java record to represent the Animal entity. This record will have fields for the scientific name, name, genus, and species, allowing you to work with animal data efficiently.

public record Animal(String scientificName, String name, String genus, String species) {
    public static Animal of(Faker faker) {
        var animal = faker.animal();
        return new Animal(
            animal.scientificName(),
            animal.name(),
            animal.genus(),
            animal.species()
        );
    }
}

This record includes a factory method, of, that generates an Animal instance with random data using the DataFaker library. We’ll use this method to populate our database with animal records.

In your Quarkus project, we’ll set up CDI (Contexts and Dependency Injection) to handle database connections and data access. Here’s an example of how to create a ConnectionSupplier class that manages database connections:

@ApplicationScoped
public class ConnectionSupplier {

    private static final Logger LOGGER = Logger.getLogger(ConnectionSupplier.class.getName());

    @Produces
    @RequestScoped
    public Connection get() throws SQLException {
        LOGGER.info("Creating connection");
        // Create and return the database connection, e.g., using DriverManager.getConnection
    }

    public void dispose(@Disposes Connection connection) throws SQLException {
        LOGGER.info("Closing connection");
        connection.close();
    }
}

The ConnectionSupplier class uses CDI annotations to produce and dispose of database connections. This allows Quarkus to manage the database connection lifecycle for you.

Let’s create the AnimalDAO class to interact with the database using JDBC. This class will have methods for inserting and querying animal data.

@ApplicationScoped
public class AnimalDAO {

    private final Connection connection;

    public AnimalDAO(Connection connection) {
        this.connection = connection;
    }

    public void insert(Animal animal) {
        try {
            // Prepare and execute the SQL INSERT statement to insert the animal data
        } catch (SQLException exception) {
            throw new RuntimeException(exception);
        }
    }

    public Optional<Animal> findById(String id) {
        try {
            // Prepare and execute the SQL SELECT statement to find an animal by ID
        } catch (SQLException exception) {
            throw new RuntimeException(exception);
        }
    }

    // Other methods for data retrieval and manipulation
}

In the AnimalDAO class, you’ll use JDBC to perform database operations. You can add more methods to handle various database tasks, such as updating and deleting animal records.

The AnimalService class will generate animal data and utilize the AnimalDAO for database interaction.

@ApplicationScoped
public class AnimalService {

    private final Faker faker;
    private final AnimalDAO dao;

    @Inject
    public AnimalService(Faker faker, AnimalDAO dao) {
        this.faker = faker;
        this.dao = dao;
    }

    // Implement methods for generating and managing animal data
}

In the AnimalService, you’ll use the DataFaker library to generate random animal data and the AnimalDAO for database operations.

With these components in place, you’ve set up the foundation for your Quarkus-based Microservice API with HarperDB. In the next part of the tutorial, we’ll dive into developing RESTful endpoints and data management.

Create AnimalResource Class

In this final part of the tutorial, we will create an AnimalResource class to expose our animal service through HTTP endpoints. Additionally, we will provide sample curl commands to demonstrate how to consume these endpoints locally.

Create an AnimalResource class with RESTful endpoints for managing animal data. This class will interact with the AnimalService to handle HTTP requests and responses.

@Path("/animals")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class AnimalResource {
    private final AnimalService service;

    public AnimalResource(AnimalService service) {
        this.service = service;
    }

    @GET
    public List<Animal> findAll() {
        return this.service.findAll();
    }

    @POST
    public Animal insert(Animal animal) {
        this.service.insert(animal);
        return animal;
    }

    @DELETE
    @Path("{id}")
    public void delete(@PathParam("id") String id) {
        this.service.delete(id);
    }

    @POST
    @Path("/generate")
    public void generateRandom() {
        this.service.generateRandom();
    }
}

In this class, we’ve defined several RESTful endpoints, including:

• GET /animals: Returns a list of all animals.
• POST /animals: Inserts a new animal.
• DELETE /animals/{id}: Deletes an animal by its ID.
• POST /animals/generate: Generates random animal data.
  
  

Here are curl commands to test the HTTP endpoints locally using http://localhost:8080/animals/ as the base URL:

Retrieve All Animals (GET)

   curl -X GET http://localhost:8080/animals/

Insert a New Animal (POST)

   curl -X POST -H "Content-Type: application/json" -d '{
       "scientificName": "Panthera leo",
       "name": "Lion",
       "genus": "Panthera",
       "species": "Leo"
   }' http://localhost:8080/animals/

Delete an Animal by ID (DELETE)

Replace {id} with the ID of the animal you want to delete:

   curl -X DELETE http://localhost:8080/animals/{id}

Generate Random Animal Data (POST)

This endpoint doesn’t require any request data:

   curl -X POST http://localhost:8080/animals/generate

These curl commands allow you to interact with the Quarkus-based microservice API, performing actions such as retrieving, inserting, and deleting animal data. The generated random data endpoint is valuable for populating your database with test data.

With these RESTful endpoints, you have a fully functional Quarkus application integrated with HarperDB to manage animal data over HTTP. You can extend and enhance this application further to meet your specific requirements. Congratulations on completing this tutorial!

Conclusion

In this tutorial, we embarked on a journey to build a Quarkus-based Microservice API integrated with HarperDB, a robust, high-performance database. We started by setting up our environment and creating a Quarkus project with the necessary extensions. Leveraging the DataFaker library, we generated random animal data to populate our HarperDB database.

The core of our application was the seamless integration with HarperDB, showcasing the capabilities of the HarperDB Java driver. We used CDI to manage database connections efficiently and created a structured data access layer with the AnimalDAO class. Through this, we performed database operations, such as inserting and querying animal data.

With the implementation of the AnimalService class, we combined the generated data with database operations, bringing our animal data management to life. Finally, we exposed our animal service through RESTful endpoints in the AnimalResource class, allowing us to interact with the service through HTTP requests.

You can explore the complete source code of this project on GitHub. Feel free to fork, modify, and extend it to suit your needs.

As you continue your journey into the world of HarperDB and Quarkus, remember to consult the comprehensive HarperDB documentation available at HarperDB Documentation to dive deeper into the capabilities and features of HarperDB.

Stay informed about the latest updates, release notes, and news on HarperDB’s official website to ensure you’re always working with the most up-to-date information. Check out the latest release notes to discover what’s new and improved in HarperDB.

By combining Quarkus and HarperDB, you’re well-equipped to build efficient and scalable applications that meet the demands of the modern digital landscape. Happy coding!