Groovy / Maven

Oracle native BOOLEAN with Micronaut Data JDBC

Learn how to map Java boolean properties to Oracle Database 23ai native BOOLEAN columns and query them with Micronaut Data JDBC.

Radovan Radic
On this guide
In this section

Getting Started

In this guide, we will create a Micronaut application written in Groovy.

In this guide, you will build a small task list with Micronaut Data JDBC and Oracle Database. Each task has a completed flag.

You will map that flag to a native Oracle BOOLEAN column and query it with repository methods that Micronaut Data translates to Oracle boolean SQL such as IS TRUE and IS FALSE.

Oracle Database 23.1 and later (including Oracle AI Database 26ai) support the SQL BOOLEAN data type. Earlier releases such as Oracle Database 19c and 21c do not, so Micronaut Data keeps its legacy mapping by default: boolean properties are stored in NUMBER(1) columns and compared with 1 and 0. You opt in to native BOOLEAN by telling Micronaut Data which Oracle version your SQL targets.

What you will need

To complete this guide, you will need the following:

Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Writing the Application

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

mn create-app example.micronaut.micronautguide \
    --features=data-jdbc,oracle,serialization-jackson \
    --build=maven \
    --lang=groovy \
    --test=spock
Note
If you don’t specify the --build argument, Gradle with the Kotlin DSL is used as the build tool.
If you don’t specify the --lang argument, Java is used as the language.
If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.

The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.

If you use Micronaut Launch, select Micronaut Application as application type and add data-jdbc, oracle, and serialization-jackson features.

Note
If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features, and apply those changes to your application.

Oracle Driver

Add also the Oracle Driver

pom.xml
<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc11</artifactId>
    <scope>runtime</scope>
</dependency>

Database Configuration

And the database configuration:

groovy/src/main/resources/application.properties

Target Oracle Database 23.1

Micronaut Data uses the target Oracle version in two places, and each has its own setting:

  • Repository SQL is generated when your code is compiled. The target version comes from the build or from the repository annotation.

  • Schema generation runs when the application starts. The target version comes from the datasource configuration.

Configure both. The datasource setting does not change SQL that was already generated for repositories at compilation time, and the compile-time setting does not change the generated DDL.

The target version tells Micronaut Data which SQL features it can use. It does not detect the database version. Use numeric major.minor notation: a major-only value such as 23 means 23.0 and does not enable features that require 23.1.

Repository SQL

There are two ways to set the target version for repository SQL:

  • For all Oracle repositories of the application, set the micronaut.data.sql.dialect-options.oracle.version option in the build, as shown below. Use this when the whole application runs against Oracle Database 23.1 or later, so the version is configured in one place.

  • For a single repository, set the version member of @JdbcRepository. A repository version takes precedence over the build setting, so you can target an individual repository differently, for example while you migrate a schema.

This guide sets the version on the repository, as you will see in the Repository section, so the generated project works without changes to the build. To target all Oracle repositories instead, configure the build as follows and remove version from the annotation.

The Groovy sources are compiled in the Maven JVM, so pass the option as a system property of that JVM, for example in .mvn/jvm.config:

.mvn/jvm.config
-Dmicronaut.data.sql.dialect-options.oracle.version=23.1

Schema Generation

Schema generation reads the target version from the datasource configuration:

groovy/src/main/resources/application.properties

Test Resources

Micronaut Test Resources starts Oracle Database Free, which supports native BOOLEAN, for tests and development:

groovy/src/main/resources/application.properties

Task

Create an entity for a task:

groovy/src/main/groovy/example/micronaut/Task.groovy

Schema generation creates the TASK table, and a TASK_SEQ sequence for the generated IDs:

CREATE TABLE "TASK" (
    "ID" NUMBER(19) NOT NULL PRIMARY KEY,
    "TITLE" VARCHAR(255) NOT NULL,
    "COMPLETED" BOOLEAN NOT NULL
)

Without the datasource target version, the COMPLETED column would be created as NUMBER(1).

Repository

Create a repository for tasks:

groovy/src/main/groovy/example/micronaut/TaskRepository.groovy

When a repository has a target version, Micronaut Data reads the database version on first use. If the database is older than the target version, it logs a warning, because Oracle Database 19c or 21c rejects the generated BOOLEAN SQL.

Controller

Expose the tasks as HTTP endpoints:

groovy/src/main/groovy/example/micronaut/TaskController.groovy

Test

Add a test for the column type, the repository queries and the HTTP endpoints:

groovy/src/test/groovy/example/micronaut/OracleBooleanSpec.groovy

Testing the Application

To run the tests:

./mvnw test

When you run the tests, Micronaut Test Resources starts an Oracle Database Free container before the application connects.

Run the Application

Start the application with ./gradlew run or ./mvnw mn:run, and create two tasks:

curl -X POST http://localhost:8080/tasks \
     -H 'Content-Type: application/json' \
     -d '{"title":"Write the guide"}'
curl -X POST http://localhost:8080/tasks \
     -H 'Content-Type: application/json' \
     -d '{"title":"Review the guide"}'

Complete the first task:

curl -X PUT http://localhost:8080/tasks/1/complete

List the completed and the open tasks:

curl http://localhost:8080/tasks/completed
curl http://localhost:8080/tasks/open

The first request returns Write the guide, and the second returns Review the guide.

To see the SQL that Micronaut Data runs, set the logger.levels.io.micronaut.data.query configuration property to DEBUG.

Micronaut Test Resources Goals

  • zero-configuration: without adding any configuration, test resources should be spawned and the application configured to use them. Configuration is only required for advanced use cases.

  • classpath isolation: use of test resources shouldn’t leak into your application classpath, nor your test classpath

  • compatible with GraalVM native: if you build a native binary, or run tests in native mode, test resources should be available

  • easy to use: the Micronaut build plugins for Gradle and Maven should handle the complexity of figuring out the dependencies for you

  • extensible: you can implement your own test resources, in case the built-in ones do not cover your use case

  • technology agnostic: while lots of test resources use Testcontainers under the hood, you can use any other technology to create resources

Next Steps

Read more about Oracle BOOLEAN Support in Micronaut Data and the Oracle SQL data types.

License

Note
All guides are released with an Apache License 2.0 for the code and a Creative Commons Attribution 4.0 license for the writing and media (images).