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.
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:
-
Some time on your hands
-
A decent text editor or IDE (e.g. IntelliJ IDEA)
-
JDK 21 or greater installed with
JAVA_HOMEconfigured appropriately -
Docker installed to run Oracle Database with Micronaut Test Resources.
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.
-
Download and unzip the source
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
<dependency>
<groupId>com.oracle.database.jdbc</groupId>
<artifactId>ojdbc11</artifactId>
<scope>runtime</scope>
</dependency>Database Configuration
And the database configuration:
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.versionoption 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
versionmember of@JdbcRepository. A repositoryversiontakes 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:
-Dmicronaut.data.sql.dialect-options.oracle.version=23.1Schema Generation
Schema generation reads the target version from the datasource configuration:
Test Resources
Micronaut Test Resources starts Oracle Database Free, which supports native BOOLEAN, for tests and development:
Task
Create an entity for a task:
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:
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:
Test
Add a test for the column type, the repository queries and the HTTP endpoints:
Testing the Application
To run the tests:
./mvnw testWhen 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/completeList the completed and the open tasks:
curl http://localhost:8080/tasks/completedcurl http://localhost:8080/tasks/openThe 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). |