PL/Java VM option recommendations

Adding to the set of readable modules

By default, a small set of Java modules (including java.base, org.postgresql.pljava, and java.sql and its transitive dependencies, which include java.xml) will be readable to any Java code installed with install_jar.

While those modules may be enough for many uses, other modules are easily added using --add-modules within pljava.vmoptions. For example, --add-modules=java.net.http,java.rmi would make the HTTP Client and WebSocket APIs readable, along with the Remote Method Invocation API.

For convenience, the module java.se simply transitively requires all the modules that make up the full Java SE API, so --add-modules=java.se will make that full API available to PL/Java code without further thought. The cost, however, may be that PL/Java uses more memory and starts more slowly than if only a few needed modules were named.

Third-party modular code can be made available by adding the modular jars to pljava.module_path (see configuration variables) and naming those modules in --add-modules. PL/Java currently treats all jars loaded with install_jar as unnamed-module, legacy classpath code.

For more, see PL/Java and the Java Platform Module System.

Byte order for PL/Java-implemented user-defined types

PL/Java is free of byte-order issues except when using its features for building user-defined types in Java. At sites with no current or planned use of those features, this section does not require attention.

The 1.5.0 release of PL/Java begins a transition affecting the byte-order defaults, which will be completed in a future release. No immediate action is recommended; there is a byte-order page for more on the topic and an advance notice of an expected future migration step.

Class data sharing

Class data sharing is a commonly-supported Java virtual machine feature that reduces both VM startup time and memory footprint by having many of Java's runtime classes preprocessed into a file that can be quickly memory-mapped into the process at Java startup, and shared if there are multiple processes running Java VMs.

How to set it up differs depending on the Java VM in use, Hotspot (in Oracle Java or OpenJDK with Hotspot), or OpenJ9 (an alternate JVM also available with OpenJDK). The instructions on this page are specific to Hotspot. For the corresponding feature in OpenJ9, which is worth a good look, see the class sharing in OpenJ9 page.

For Hotspot, the class data sharing is enabled by including -Xshare:on or -Xshare:auto in the pljava.vmoptions string. In rough terms in 64-bit Java 8 it can reduce the ‘Metaspace’ size per PL/Java backend by slightly over 4 MB, and cut about 15 percent from the PL/Java startup time per process.

Sharing may be enabled automatically if the Java VM runs in client mode (described below), but may need to be turned on with -Xshare:on or -Xshare=auto if the VM runs in server mode.

The on setting can be useful for quickly confirming that sharing works, as it will report a hard failure if anything is amiss. However, auto is recommended in production: on an operating system with address-space layout randomization, it is possible for some backends to (randomly) fail to map the share. Under the auto setting, they will proceed without sharing (and with higher resource usage, which may not be ideal), where with the on setting they would simply fail.

Note: the earliest documentation on class data sharing, dating to Java 1.5, suggested that the feature was not available at all in server mode. In recent VMs that is no longer the case, but it does have to be turned on.

To confirm that sharing is on, look at PL/Java's startup message for a line similar to:

Java HotSpot(TM) 64-Bit Server VM (25.74-b02, mixed mode, sharing)

To see the startup message after PL/Java is already installed, use

SET client_min_messages TO debug1;

in a new session, before executing any PL/Java function;

SELECT sqlj.get_classpath('public');

for example.

An error has occurred while processing the shared archive file.
Specified shared archive not found.

-XX:AOTLibrary=

JDK 9 and later have included a tool, jaotc, that does ahead-of-time compilation of class files to native code, producing a shared-object file that can be named with the -XX:AOTLibrary option. Options to the jaotc command can specify which jars, modules, individual classes, or individual methods to compile and include. Optionally, jaotc can include additional metadata with the compiled code (at the cost of a slightly larger file), so that the Java runtime's tiered JIT compiler can still further optimize the compiled-in-advance methods that turn out to be hot spots.

To make a library of manageable size, a list of touched classes and methods from a sample run can be made, much as described above for application class data sharing.

A blog post by Matthew Gilliard reports successfully combining jaotc compilation and application class data sharing with good results, and goes into some detail on the preparation steps.

-XX:+DisableAttachMechanism

Management and monitoring tools like jvisualvm (included with the Oracle JDK) can show basic information about any running Java process, but can show much more detailed information by ‘attaching’ to the process.

By default, attachment requires the tool to be run on the same host as the database server, and under the same identity. Those existing restrictions should satisfy most security requirements (after all, a local process under the postgres identity has many other ways to bypass PostgreSQL's assurances), but there can also be non-security-related reasons to add the -XX:+DisableAttachMechanism option:

Interaction with class data sharing

Depending on the versions of Java and jvisualvm, it is possible for jvisualvm to hang after selecting a Java process to display, if that VM has class data sharing enabled. In such cases, adding -XX:+DisableAttachMechanism to the VM options will ensure that jvisualvm can at least display the usual overview information that is available when it cannot attach.

Memory footprint

In Java 8, running the VM with -XX:+DisableAttachMechanism seems to reduce the necessary MetaspaceSize by about 3 megabytes.

client and server VM

A Java VM may be able to operate in a client mode (optimized for starting small apps with minimal latency), or a server mode, tailored to large, long-running apps emphasizing throughput. Typically the server mode is selected automatically if a ‘server class’ (large memory or 64-bit) platform is detected.

PostgreSQL will often be run on ‘server class’ platforms, causing the VM to select server mode, when the usage pattern in PL/Java more closely resembles the client scenario.

While there is no one simple option to force client mode if the VM has selected server, it is possible to adjust individual settings to more appropriate values.

The heap size settings are important, because the defaults on a server-class machine will be to grab a substantial fraction of all memory. In a PL/Java application where many processes may run, it is more important to choose smaller heap sizes close to what is actually needed. The size can be set with -Xms to give a starting size, which the VM can expand if needed; this is a safe option when you have an idea what the usual case memory demand will be, but are not confident about the maximum that could sometimes be needed. A hard limit can be set with -Xmx if you know a heap size that your code should never need to exceed.

The choice of garbage collector can also affect the memory footprint, as the different collectors incur different memory overheads. If it performs adequately for the application, the Serial collector seems to lead the choices in space efficiency, followed by ConcMarkSweep. The G1 collector, favored as ConcMarkSweep's replacement, uses slightly more space to work, while Parallel and ParallelOld will occupy more than double the space of any of these.

-Xshare:on -XX:+DisableAttachMechanism -Xms2m -XX:+UseSerialGC