Add JPA to MicroProfile Starter generated project

This guide shows the steps to add JPA support to an application generated by the MicroProfile Starter project for Payara Micro.

Using MySQL database.

1) Start by generating a project using the [MicroProfile Starter website](https://start.microprofile.io). You can use the Command Line to create a project for Payara Micro without any examples of the MicroProfile specifications.

curl -O -J 'https://start.microprofile.io/api/project?supportedServer=PAYARA_MICRO'

2) Add the Jakarta Web profile maven dependencies to the project to have access to the JPA API. Set the scope to provided as all required dependencies are already bundled within Payara Micro Enterprise.

<dependency>
    <groupId>jakarta.platform</groupId>
    <artifactId>jakarta.jakartaee-web-api</artifactId>
    <version>8.0.0</version>
    <scope>provided</scope>
</dependency>

3) Add the persistence.xml file to define the Persistence unit. Create a file src/main/resources/META-INF/persistence.xml wit the following content

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.1" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd">
    <persistence-unit name="demoPU" transaction-type="JTA">
        <jta-data-source>jdbc/local-db</jta-data-source>
    </persistence-unit>
</persistence>

Important to note here is the JNDI name of the DataSource we need to create in one of the following steps.

4) Define the JPA Entities and use @PersistenceContext just as you would do when using JPA in any Java EE or Jakarta EE compliant runtime.

5) Create a post-boot command file that will create the DataSource when Payara Micro starts up. The file name and location is of no importance but needs to be referenced when launching the application.

create-jdbc-connection-pool --datasourceclassname com.mysql.jdbc.jdbc2.optional.MysqlDataSource --restype javax.sql.DataSource demo-pool
set resources.jdbc-connection-pool.demo-pool.property.password=password resources.jdbc-connection-pool.demo-pool.property.databaseName=fishes resources.jdbc-connection-pool.demo-pool.property.serverName=localhost resources.jdbc-connection-pool.demo-pool.property.user=demo resources.jdbc-connection-pool.demo-pool.property.portNumber=3306

create-jdbc-resource --enabled=true --poolName=demo-pool --target=domain jdbc/local-db
create-resource-ref --enabled=true --target=server jdbc/local-db

Important here is the database information like Server name, user name, and password. They can be specified as variables so that you can define them with JVM System parameters, environment variables, or Kubernetes Secrets, but there is no need to do this since they are defined in this external file which is already environment specific and not registered in the Source repository.

6) Compile and package the application.

mvn clean package

7) Launch the application, using the post-boot command file and adding the MySQL JDBC jar.

java -jar target/demo-microbundle.jar --postbootcommandfile /path/to/postboot --addlibs /path/to/mysql-connector-java-5.1.39

Instead of creating and using the FAT JAR, it is recommended to use the hollow JAR approach supported by Payara Micro Enterprise.

java -jar payara-micro.jar target/demo.war --postbootcommandfile /path/to/postboot --addlibs /path/to/mysql-connector-java-5.1.39

In this case, you can remove the Payara Micro plugin from the Maven project.

Using PostgreSQL database.

When using PostgreSQL database, follow the guide for the MySQL database with small changes in steps 5 and 7.

Change the post-boot command file in step 5 to use PostgreSQL specific configuration.

create-jdbc-connection-pool --datasourceclassname org.postgresql.ds.PGSimpleDataSource --restype javax.sql.DataSource demo-pool
set resources.jdbc-connection-pool.demo-pool.property.password=password resources.jdbc-connection-pool.demo-pool.property.databaseName=fishes resources.jdbc-connection-pool.demo-pool.property.serverName=localhost resources.jdbc-connection-pool.demo-pool.property.user=postgres resources.jdbc-connection-pool.demo-pool.property.portNumber=5432

create-jdbc-resource --enabled=true --poolName=demo-pool --target=domain jdbc/local-db
create-resource-ref --enabled=true --target=server jdbc/local-db

Use the PostgreSQL JDBC jar in step 7.

--addlibs /path/to/postgresql-42.2.9.jar