Oracle SQLcl and JavaScript​: moving to GraalVM for JDK 25

Two things are different on GraalVM for JDK 25 compared to the GraalVM 17 setup from the previous post.

First, there is no gu. The component installer was removed with GraalVM for JDK 21, so you cannot add JavaScript to the JDK the way we did last time. Languages are now ordinary Maven artifacts.

Second, and this is the part that actually bites, GraalVM stopped bundling the JSR-223 ScriptEngine starting with GraalVM for JDK 21. The javax.script bridge that SQLcl's script command looks up through ScriptEngineManager.getEngineByName(...) is now a separate artifact, org.graalvm.js:js-scriptengine, that has to be present explicitly. And SQLcl does not carry the GraalJS runtime for you, so the language itself has to be supplied as well.

On GraalVM 17, Linux boxes hid this by getting JavaScript from the OS. Installing the graalvm-17-javascript, graalvm-17-regex, and graalvm-17-icu4j RPMs (the yum form of gu install js) put the engine into the JDK, and SQLcl picked it up from there. Those language RPMs do not exist for JDK 21 and later. A yum search graalvm on JDK 25 returns only graalvm-25-jdk and graalvm-25-native-image, and no graalvm-25-javascript.

So both sources are gone at once: the JDK no longer ships the language, and SQLcl never did. On a clean SQLcl install $SQL_HOME/lib/ext contains the dbtools-* and oci-* jars but nothing from GraalJS. The fix is to fetch the complete, version-matched GraalJS stack, js-scriptengine included, from Maven and drop it into lib/ext.

On GraalVM for JDK 25, the first script call gives you this:

SQL> script
  2  ctx.write('test\n');
  3* /
JavaScript engine not found.
GraalVM with Nodejs/Javascript support is required.
Download
	https://www.oracle.com/downloads/graalvm-downloads.html
Ensure NodeJS/Javascript is installed following documentation
	https://docs.oracle.com/en/graalvm/jdk/17/docs/reference-manual/graalvm-updater/#install-components

That message is SQLcl's fallback when the engine lookup returns null. It is not telling you the runtime is absent. It is telling you the JSR-223 factory was not registered, because the bridge jar is not on the classpath.

The simplest way that works the same on Linux and macOS is SDKMAN, which installs the JDK and manages JAVA_HOME and PATH for you:

# find the current 25 Oracle GraalVM, e.g. 25.0.4-graal
sdk list java | grep graal          
sdk install java 25.0.4-graal
# sets JAVA_HOME and PATH for this shell:
sdk use java 25.0.4-graal           
java -version

Use sdk default java 25.0.4-graal to make it the default for new shells. That is all you need on either platform, and you can skip to Step 2.

If you prefer platform-native installs, use one of these instead.

On macOS with Homebrew:

brew install --cask graalvm-jdk@25
export JAVA_HOME=$(/usr/libexec/java_home -v 25)

The JDK lands under /Library/Java/JavaVirtualMachines/ and participates in the java_home mechanism, so there is no need to hardcode the path. If macOS blocks the unsigned bundle on first launch, clear the quarantine flag on the install directory once with sudo xattr -r -d com.apple.quarantine.

On Oracle Linux or RHEL, install straight from Oracle's yum repo. This is the cleanest route on those distributions and keeps the JDK on the dnf/yum update stream:

sudo yum install graalvm-25-jdk
export JAVA_HOME=/usr/lib64/graalvm/graalvm-java25
export PATH="$JAVA_HOME/bin:$PATH"
java -version

Prefer graalvm-25-jdk over graalvm-25-native-image here, since you do not need Native Image or its LLVM and toolchain dependencies just to run SQLcl. If your box already has graalvm-17-* installed, both JDKs live side by side under /usr/lib64/graalvm, so point JAVA_HOME at the 25 directory explicitly rather than relying on alternatives, to be sure SQLcl does not run on 17. If yum does not offer the package, your channel may not carry it; yum search graalvm | grep 25 shows what is available, and the SDKMAN route above or the Oracle archive tarball (https://download.oracle.com/graalvm/25/latest/graalvm-jdk-25_linux-x64_bin.tar.gz, aarch64 on ARM) both work as fallbacks.

Whichever route you take, SQLcl's sql launcher honours JAVA_HOME, so your next SQLcl session runs on GraalVM 25. Verify from inside SQLcl with show java.

SQLcl builds its classpath from $SQL_HOME/lib/ext/*, so confirm there is no GraalJS there yet:

cd "$SQL_HOME"        # your SQLcl install root, e.g. .../sqlcl
ls -1 lib/ext/polyglot-*.jar lib/ext/truffle-*.jar lib/ext/js-*.jar 2>/dev/null

On a clean install this prints nothing. lib/ext holds the dbtools-* and oci-* jars, but none of the GraalJS runtime and no js-scriptengine.

Since there is nothing to match, pin the GraalJS version to the GraalVM JDK you installed, so the Truffle runtime lines up with the JDK it executes on. Read it from:

java -version

and use that 25.0.x patch as the version in the next step. If you later run this on a machine where you have already copied the jars in, the same version keeps the set consistent.

Following Chris Hoina's ORDS article, the practical way to do this is a throwaway Maven project whose only job is to resolve the GraalJS dependency set so you can copy the jars into lib/ext. You pin the whole stack in a pom, which makes the result reproducible: one committable pom.xml and one fetch command, which is exactly what you want in a DevOps pipeline.

Create a quickstart project and change into it:

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app \
  -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DinteractiveMode=false
cd my-app

Add the three GraalJS dependencies to the <dependencies> section of the generated pom.xml. Pin the version to your GraalVM JDK from Step 2, because the whole set has to line up with the GraalVM you run:

<dependency>
    <groupId>org.graalvm.polyglot</groupId>
    <artifactId>polyglot</artifactId>
    <version>25.0.4</version>
</dependency>
<dependency>
    <groupId>org.graalvm.polyglot</groupId>
    <artifactId>js</artifactId>
    <version>25.0.4</version>
    <type>pom</type>
</dependency>
<dependency>
    <groupId>org.graalvm.js</groupId>
    <artifactId>js-scriptengine</artifactId>
    <version>25.0.4</version>
</dependency>

The org.graalvm.polyglot:js pom pulls in the language and the full Truffle runtime, and org.graalvm.js:js-scriptengine adds the JSR-223 bridge that SQLcl needs and does not ship. Note that the bridge lives under org.graalvm.js, not org.graalvm.polyglot. Now resolve the closure straight into SQLcl's extensions directory, in one command:

mvn dependency:copy-dependencies \
  -DincludeScope=runtime \
  -DoutputDirectory="$SQL_HOME/lib/ext"

-DincludeScope=runtime keeps the quickstart's test jars out (junit-*, apiguardian-api, opentest4j are test scope), so only the GraalJS runtime and the bridge land in lib/ext. -DoutputDirectory writes them there directly, so there is no separate copy step and nothing unnecessary to clean up afterwards. Because every jar is pinned to your GraalVM version, the stack in lib/ext is internally consistent and matched to the JDK it runs on.

Confirm the set landed, and that the bridge in particular is now present:

ls -1 "$SQL_HOME"/lib/ext/js-scriptengine-*.jar \
      "$SQL_HOME"/lib/ext/polyglot-*.jar \
      "$SQL_HOME"/lib/ext/truffle-runtime-*.jar

installed java script jars

The classpath is assembled at launch, so a running SQLcl will not see the new jar. Start a fresh session:

SQL> script
  2  ctx.write('test\n');
  3* /
test

If test prints, the bridge is registered and a polyglot context initialised on GraalVM 25.

The workarounds from part one still apply here. Running a .js file directly with script myscript.js can still throw Unknown identifier: write unless an empty script block has been evaluated first in the session, so the run.sql helper I described last time (with the dummy script ; / prelude) is still what I use to run scripts across a project. Nothing about moving to GraalVM 25 changes that.

The engine now works, but the first real script may fail like this:

SyntaxError: helper.js:205:0 Expected an operand but found const
const aliasToApplication = {
^

This is neither your script nor the jar. SQLcl launches the engine with -Dpolyglot.js.nashorn-compat=true so its own bindings behave like the old Nashorn engine. Nashorn compatibility mode sets the ECMAScript version to 5 by default, and ES5 predates let and const. The parser dies on the first const, and everything after it cascades.

You do not want to disable nashorn-compat, because SQLcl relies on its Nashorn style Java interop for the injected ctx object. You just raise the language level on top of it, which GraalJS supports. Add one line to the sql launcher next to the existing option:

# in $SQL_HOME/bin/sql, just after the AddVMOption for nashorn:
AddVMOption -Dpolyglot.js.ecmascript-version=2024

Use a finalised year such as 2024 rather than latest or staging, for predictable behaviour. It covers const, let, arrow functions, template literals, and the rest of modern JavaScript. For a quick check without editing the launcher, the same option works through JAVA_TOOL_OPTIONS:

JAVA_TOOL_OPTIONS="-Dpolyglot.js.ecmascript-version=2024 -Dfile.encoding=UTF-8" sql /nolog

Keeping it in the launcher is the better long term state, since it scopes the setting to SQLcl instead of every JVM on the machine.

One caveat worth flagging: none of this ECMAScript pinning was necessary on GraalVM 17. The same helper.js, const and all, ran there without ever setting ecmascript-version, and it still does on the very same SQLcl 26.2 used here. So this is not a SQLcl change. With SQLcl held constant, GraalVM 17 needs no pin and GraalVM 25 does, and both are launched with the same nashorn-compat=true flag, which puts the difference in GraalJS itself: the 23.0.x that shipped with the GraalVM 17 component did not apply an ES5 default under nashorn-compat, and the 25.0.x fetched from Maven does. Which GraalJS release changed that, and the exact mechanism, I have not pinned down. If you know, I would like to hear it (see the open questions below).

Once everything runs you will still see this at engine init:

WARNING: A terminally deprecated method in sun.misc.Unsafe has been called
WARNING: sun.misc.Unsafe::objectFieldOffset has been called by
  com.oracle.truffle.runtime.hotspot.HotSpotTruffleRuntime (.../truffle-runtime-25.0.4.jar)
WARNING: sun.misc.Unsafe::objectFieldOffset will be removed in a future release

This is cosmetic on JDK 25 and it is not yours to fix. It originates inside Truffle's HotSpotTruffleRuntime and is tracked upstream on oracle/graal in issues #12623 and #12782. The real fix has to come from a Truffle build that moves off the deprecated memory access methods.

One thing to keep on the radar for the next JDK jump: JDK 26 changes the default so that calling these methods throws rather than warns. On JDK 25 you are only warned, but once you move SQLcl onto a JDK 26 runtime, engine init would fail unless Truffle has migrated by then. The escape hatch, if you need it there, is AddVMOption --sun-misc-unsafe-memory-access=allow. On JDK 25 I leave it unset. Do not reach for --enable-native-access=org.graalvm.truffle to silence it, since SQLcl loads Truffle from the classpath rather than as a named module, so that flag only produces its own "Unknown module" warning, and the launcher already grants --enable-native-access=ALL-UNNAMED in any case.

Two things I have not fully resolved, and I would like to hear how they look on your systems.

Performance. My subjective impression is that JavaScript execution feels slower on GraalVM 25 than it did on GraalVM 17. This is a gut feeling, not a measurement, so treat it as such. Worth noting that the optimizing Truffle runtime is definitely engaged, the sun.misc.Unsafe warning in Step 6 comes from HotSpotTruffleRuntime and not from an interpreter fallback, so if there is a regression it is not simply the engine running interpreted. If you drive SQLcl scripts on both, I would be interested to hear whether you see the same, on what kind of workload, and whether it shows up in startup, warmup, or steady state. Comments welcome.

The ECMAScript default. As shown in Step 5, the ecmascript-version pin is needed on GraalVM 25 but not on GraalVM 17, on the same SQLcl 26.2 and the same nashorn-compat flag, so the change is in GraalJS between 23.0.x and 25.0.x, not in SQLcl. What I have not pinned down is which GraalJS release started applying an ES5 default under nashorn-compat, and why. If you know the release or the rationale, please leave a comment.

In total the following changes are applied (we put our sqlcl into git):

Summary of changes to get sqlcl 26.2 compatible with graalvm-25

Part one kept our pipelines alive by moving to GraalVM 17 and gu install js. That door is now closed, both technically, because gu is gone, and on the calendar, because GraalVM 17 leaves regular Premier Support in September 2026. On GraalVM for JDK 25 the equivalent setup is:

1. The full GraalJS stack, org.graalvm.js:js-scriptengine bridge included, pinned to your GraalVM JDK version, fetched with a single scoped mvn dependency:copy-dependencies straight into lib/ext. SQLcl ships none of it, so all of it comes from Maven.

2. -Dpolyglot.js.ecmascript-version=2024, to lift the ES5 default that nashorn-compat mode imposes, so const and the rest of modern JavaScript parse.

3. Awareness that the sun.misc.Unsafe warning is benign on 25 and tracked upstream, with --sun-misc-unsafe-memory-access=allow waiting for the JDK 26 jump.

No gu, no launcher rebuild, no module path juggling, and you stay on a current GraalVM. As I noted last time, it keeps getting more involved to run JavaScript inside SQLcl due to the shifting JDK requirements, but the engine is worth it, and once these pieces are in place our existing scripts run unchanged. Credit again to Chris Hoina's ORDS writeup for the Maven approach this builds on.