Using Ebean ORM with YugabyteDB

Ebean is a Java-based Object–Relational Mapping (ORM) application. It is more user-friendly and understandable than traditional ORM tools, such as Hibernate. It achieves this by employing a session-less design that eliminates the concepts of detached/attached beans as well as the difficulties related with flushing/clearing.

Even better, Ebean supports YugabyteDB, a 100% open source, distributed SQL database built to accelerate cloud native agility, lower costs, and reduce risks without vendor lock-in. You can find more information about this integration here.

In this blog, we show you how to:

• Start a YugabyteDB cluster on your local Engine.
• Create a new Java-based Play Framework application.
• Create a simple REST API using Ebean ORM on YugabyteDB.

Starting a YugabyteDB cluster

You must have the YugabyteDB cluster installed before starting it on your local engine. To install YugabyteDB on your system, follow the steps mentioned here.

• To create a single-node local cluster with a replication factor (RF) of 1, run the following command:

$ ./bin/yugabyted start

• Check the cluster status by running the following command:

$ ./bin/yugabyted status

Now, for this blog, we will be working in a new database. So, start the YSQL shell by first going to your YugabyteDB installation directory:

cd /<path-to-yugabytedb>

Next, connect the ysql shell:

$ ./bin/ysqlsh

And finally, create the database:

# CREATE DATABASE ysql_ebeans

You should see the below output:

Creating a new Java Play Framework application

1. First, make sure you’ve completed the below prerequisites before creating the project:

• Ensure Java Development Kit (JDK) 1.8.0—or later—is installed.
• Install SBT 1.2.8.

2. Next, create a new Play-java project:

$ sbt new playframework/play-java-seed.g8

After some downloads, you’ll receive the following output:

3. From there, go to the project directory:

$ cd demo-ebean

4. Next, change the version in build.properties under the project directory to the following:

5. Finally, download dependencies with $ sbt compile.

Your new java-Play project’s folder structure is now ready to work on.

Building a REST API using Ebean and YugabyteDB

Let’s get started building the application. Our application will have an Employee model that retrieves employee information, such as first name, last name, position, and department. An EmployeeController will then store and retrieve the new employee information in the database using a Rest API.

Initial steps

1. To begin using Ebean in the application, add the plugin project/plugins.sbt as follows:

And enable the PlayEbean plugin in the build.sbt file by adding PlayEbean as highlighted below:

2. In case your default port is already in use or you want to change the port, change the settings by adding the below highlighted code to the build.sbt file:

3. Next, connect to YugabyteDB by adding the following configuration to the conf/application.conf file:

Add the following dependencies for the Yugabyte JDBC smart-driver to the build.sbt file to install  libraries for configuration.

Going deeper

1. Create a folder in the app directory as models that will contain all the Entities we create.

2. To use this directory as a default Ebean package of classes, add the below code at the end of conf/application.conf.

3. Next, create a file under app/models/ as Employee.java. This is the class definition or information for the employee. Add the below code to that file:

4. Create a file as app/controllers/ as EmployeeController.java. This file will control the flow of data of employees. It consists of methods for all API calls, such as adding an employee and retrieving employee information. Add the below code to that file as follows:

5. Next, add the GET and POST API Request for the /employees endpoint to the conf/routes file. This will define the necessary method for receiving the request:

Compile and run

1. Now compile and run the server using $ sbt compile and $ sbt run in the project directory.

2. From here, check the functioning of the API created with curl commands as follows:

• To create an employee using a POST request:

$ curl --data '{ "firstName" : "John", "lastName" : "Smith",

"email":"jsmith@xyz.com" }' -v -X POST -H

'Content-Type:application/json' https://localhost:8080/employees

• To get the details of the employees using a GET request:

$ curl  -v -X GET https://localhost:8080/employees

The output should look like the following:

3. Finally, find the structure of the employee table using # \d employee and then verify the insertion of employee detail in that table in the database using # select * from employee;.

Next steps

1. Check out the Github issue for more information about the work done for testing support of the Ebean ORM with YugabyteDB.

2. Check out our orm-examples repository. It has a more realistic use case (i.e., a simple online e-commerce store) of using Ebean ORM with YugabyteDB.

3. Give Yugabyte Cloud a try by signing up for a free tier account in a couple of minutes.

Got questions? Feel free to ask them in our YugabyteDB community Slack channel.