GraalVM native-image

Native-image support is not a different execution model for Ekbatan. Actions, repositories, optimistic locking, sharding, and outbox writes behave the same as on the JVM. The native-specific work is making GraalVM aware of reflection targets, SQL resources, programmatic Flyway migration resources, and the libraries used by the selected stack.

The Moving Parts

Required App Configuration

Add ekbatan-native

Add the module to applications that build native binaries:

implementation("io.github.zyraz-io:ekbatan-native:0.2.1")

or Maven:

<dependency>
  <groupId>io.github.zyraz-io</groupId>
  <artifactId>ekbatan-native</artifactId>
  <version>0.2.1</version>
</dependency>

If your app calls Ekbatan’s programmatic Flyway migrator, also add ekbatan-flyway:

implementation("io.github.zyraz-io:ekbatan-flyway:0.2.1")

<dependency>
  <groupId>io.github.zyraz-io</groupId>
  <artifactId>ekbatan-flyway</artifactId>
  <version>0.2.1</version>
</dependency>

Set Scan Packages

The default scan root is io.ekbatan. Add your application root package at native-image build time:

If this is missing, native runtime failures usually mention record components, action params records, event payload records, builder methods, or generated jOOQ classes.

Include SQL Resources

If Flyway runs from classpath migrations, include them in the image:

graalvmNative {
    binaries.all {
        resources.includedPatterns.add("db/migration/.*\\.sql")
        resources.includedPatterns.add(".*_init\\.sql")
    }
}

Maven equivalent:

<buildArg>-H:IncludeResources=db/migration/.*\.sql</buildArg>

Use a different pattern if your app stores migrations somewhere else.

Use A Native-Image-Capable Toolchain

Gradle native examples require Java 25 and nativeImageCapable.set(true), not a hard-coded GraalVM vendor. That works locally with SDKMAN/asdf/system GraalVM installs and also works in CI with actions/setup-java using distribution: graalvm.

If Gradle chooses the wrong Java 25 installation, set JAVA_HOME to the GraalVM JDK or pin the build with:

./gradlew -Dorg.gradle.java.installations.paths="$JAVA_HOME" \
  -Dorg.gradle.java.installations.auto-detect=false \
  nativeTest

What ekbatan-native Auto-Loads

Each feature is registered through META-INF/native-image/.../native-image.properties. Features detect their target libraries and no-op when the library is absent.

ekbatan-native also bundles HikariCP reachability metadata. The jOOQ native substitution for Internal.arrayType(...) lives in ekbatan-core and is applied automatically.

Jackson 3 Records And Builders

Ekbatan serializes events with Jackson 3 (tools.jackson.databind.*). Jackson needs reflection metadata for records, action params, event payloads, generated builders, and some value factories. Jackson3RecordsFeature scans the configured packages and registers both:

• bulk query metadata, so reflection queries such as getDeclaredMethods() work; and
• per-member invocation metadata, so Jackson can actually invoke constructors, methods, and record accessors at runtime.

Both are needed on GraalVM 25.

Flyway On Native

Flyway’s normal classpath scanner does not always work inside a native image because classpath resources are not exposed as normal file: or jar: directories. Ekbatan supports two patterns, and the examples use them differently by stack.

FlywayMigrator is a wrapper around normal Flyway configuration. On the JVM it behaves like inline Flyway.configure().dataSource(...).locations(...).load().migrate(). In a native image it installs an internal resource scanner that can walk bundled classpath: migrations.

import io.ekbatan.flyway.FlywayMigrator;

FlywayMigrator.migrate(jdbcUrl, username, password);
FlywayMigrator.migrate(jdbcUrl, username, password, "classpath:db/migration", "classpath:db/seed");
FlywayMigrator.migrate(shardingConfig); // runs on every primary shard, sequentially

Build And Test Commands

The exact command depends on the stack:

Ekbatan’s Heavy Verification workflow runs JVM tests plus native builds/tests for the examples. The root Gradle native sweep uses:

./gradlew nativeTest --parallel --max-workers=4 --continue --stacktrace

Use that as heavy verification, not as the normal edit-compile-test loop.

Troubleshooting

• native-image is missing or Gradle selects Temurin/OpenJDK. Use a Java 25 GraalVM JDK and make sure Gradle sees the native-image capable installation.
• Jackson cannot deserialize action params or events. Add your application package to io.ekbatan.graalvm.scan.packages.
• Flyway sees no migrations. Include db/migration/*.sql as native resources and use the Flyway pattern for your stack.
• Quarkus and HikariCP. Quarkus prefers Agroal and does not consume all generic RMR metadata automatically. Depending on ekbatan-native is the simplest way to bring Ekbatan’s HikariCP metadata into the native classpath.
• Micronaut native tests and Hikari DEBUG logging. The Micronaut native examples ship a minimal logback.xml that keeps Hikari below DEBUG, avoiding reflection over every JavaBean property during startup.

See Also

• Learn -> Compiling to a native binary - tutorial-level walkthrough
• Wiring with Spring Boot - Spring AOT and Flyway details
• Wiring with Quarkus - Quarkus native and Flyway details
• Wiring with Micronaut - Micronaut native and serde details
• ekbatan-examples/*-native-* - runnable native wallet examples