Installation

This page covers everything you need to add Storm to your project: prerequisites, dependency setup, and optional modules.

Prerequisites

Requirement	Version
JDK	21 or later
Kotlin (if using Kotlin)	2.0 or later
Build tool	Maven 3.9+ or Gradle 8+
Database	Any JDBC-compatible database

Kotlin users do not need any preview flags. Java users must enable --enable-preview in their compiler configuration because the Java API uses String Templates (JEP 430).

Gradle Plugin (Recommended)

The Storm Gradle plugin collapses the whole setup into one plugin application. It imports the BOM, adds the core dependencies for your language, wires the metamodel processor, selects the Kotlin compiler-plugin variant matching your Kotlin version, and configures the Java preview flags. Requires Gradle 8.5+.

Kotlin

plugins {
    kotlin("jvm") version "2.4.0"
    id("com.google.devtools.ksp") version "2.3.10"
    id("st.orm") version "1.13.0"
}

That is the entire Storm setup. KSP stays in your plugins block because its version is paired to your Kotlin version; when it is missing, the build fails with the exact line to add.

Java

plugins {
    java
    id("st.orm") version "1.13.0"
}

That is the entire Storm setup, including the --enable-preview flags on compilation, tests, and execution that storm-java21's String Templates (JEP 430) require. Use a JDK 21 toolchain: preview class files are version-locked, so storm-java21 runs on JDK 21 exactly.

The plugin configures, per language path:

	Kotlin	Java
BOM	storm-bom imported as a platform	storm-bom imported as a platform
API	storm-kotlin	storm-java21
Engine	storm-core (runtime only)	storm-core (runtime only)
Metamodel	storm-metamodel-ksp on ksp	storm-metamodel-processor on annotationProcessor
Compiler plugin	storm-compiler-plugin-<variant> matching the Kotlin version	—
Compiler flags	—	--enable-preview on compile, test, and exec tasks

All Storm coordinates use the plugin's own version; the plugin and the artifacts are released together. Because the BOM is imported, optional modules stay version-less: runtimeOnly("st.orm:storm-postgresql") just works.

The storm { } extension covers the cases where the defaults do not fit:

storm {
    metamodel.set(true)               // metamodel generation (default true)
    compilerPlugin.set(true)          // Kotlin: Storm compiler plugin (default true)
    compilerPluginVariant.set("2.4")  // pin the variant, e.g. for a newer Kotlin than the plugin knows
    javaPreview.set(true)             // Java: --enable-preview flags (default true)
}

In mixed Kotlin/Java projects the Kotlin path wins: KSP processes Java declarations too. If you specifically need the Java annotation processor as well, add annotationProcessor("st.orm:storm-metamodel-processor") manually.

Maven users and Gradle users who prefer explicit configuration continue with the manual setup below.

Add the BOM

Storm provides a Bill of Materials (BOM) for centralized version management. Import the BOM once, then omit version numbers from individual Storm dependencies. This prevents version mismatches between modules.

Kotlin

dependencies {
    implementation(platform("st.orm:storm-bom:1.13.0"))
}

Java

Maven:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>st.orm</groupId>
            <artifactId>storm-bom</artifactId>
            <version>1.13.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Gradle (Kotlin DSL):

dependencies {
    implementation(platform("st.orm:storm-bom:1.13.0"))
}

Add the Core Dependencies

Kotlin

plugins {
    id("com.google.devtools.ksp") version "2.0.21-1.0.28"
}

dependencies {
    implementation(platform("st.orm:storm-bom:1.13.0"))

    implementation("st.orm:storm-kotlin")
    runtimeOnly("st.orm:storm-core")
    ksp("st.orm:storm-metamodel-ksp")
    kotlinCompilerPluginClasspath("st.orm:storm-compiler-plugin-2.0")
}

The storm-metamodel-ksp dependency generates type-safe metamodel classes (e.g., User_, City_) at compile time. See Metamodel for details. The storm-compiler-plugin automatically wraps string interpolations inside SQL template lambdas, making queries injection-safe by default. The 2.0 suffix matches the Kotlin major.minor version used in your project (e.g., storm-compiler-plugin-2.1 for Kotlin 2.1.x). See String Templates for details.

Java

Gradle (Kotlin DSL):

dependencies {
    implementation(platform("st.orm:storm-bom:1.13.0"))

    implementation("st.orm:storm-java21")
    runtimeOnly("st.orm:storm-core")
    annotationProcessor("st.orm:storm-metamodel-processor")
}

tasks.withType<JavaCompile> {
    options.compilerArgs.add("--enable-preview")
}

tasks.withType<Test> {
    jvmArgs("--enable-preview")
}

Maven:

<dependencies>
    <dependency>
        <groupId>st.orm</groupId>
        <artifactId>storm-java21</artifactId>
    </dependency>
    <dependency>
        <groupId>st.orm</groupId>
        <artifactId>storm-core</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>st.orm</groupId>
        <artifactId>storm-metamodel-processor</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>

Enable preview features for String Templates (JEP 430):

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <release>21</release>
        <compilerArgs>
            <arg>--enable-preview</arg>
        </compilerArgs>
    </configuration>
</plugin>

The metamodel processor generates type-safe metamodel classes (e.g., User_, City_) at compile time. See Metamodel for details.

Optional Modules

Storm is modular. Add only what you need.

Database Dialects

Storm works with any JDBC-compatible database out of the box. Dialect modules provide database-specific optimizations (e.g., native upsert syntax, tuple comparisons). Add the one that matches your database as a runtime dependency:

Module	Database
storm-oracle	Oracle
storm-mssqlserver	SQL Server
storm-postgresql	PostgreSQL
storm-mysql	MySQL
storm-mariadb	MariaDB
storm-sqlite	SQLite
storm-h2	H2

runtimeOnly("st.orm:storm-postgresql")

See Database Dialects for what each dialect provides.

Spring Boot Integration

For Spring Boot applications, use the starter modules instead of the base modules. The starters auto-configure the ORMTemplate bean, enable repository scanning, and integrate with Spring's transaction management. See Spring Integration for full setup details.

Kotlin

implementation("st.orm:storm-kotlin-spring-boot-starter")

Java

<dependency>
    <groupId>st.orm</groupId>
    <artifactId>storm-spring-boot-starter</artifactId>
</dependency>

Ktor Integration

For Ktor applications, add the Ktor plugin module. It provides a Storm plugin that manages the DataSource lifecycle, reads HOCON configuration, and exposes the ORMTemplate through extension properties on Application, ApplicationCall, and RoutingContext. See Ktor Integration for full setup details.

implementation("st.orm:storm-ktor")

For testing:

testImplementation("st.orm:storm-ktor-test")

JSON Support

Storm supports storing and reading JSON-typed columns. Pick the module that matches your serialization library:

Module	Library
storm-jackson2	Jackson 2.17+ (Spring Boot 3.x)
storm-jackson3	Jackson 3.0+ (Spring Boot 4+)
storm-kotlinx-serialization	Kotlinx Serialization

See JSON Support for usage details.

Observability

Module	Provides
storm-micrometer	Micrometer Observations for queries and transactions (storm.query, storm.transaction), the OpenTelemetry database semantic conventions, and trace-context SQL comments

The Spring Boot starters include storm-micrometer; Ktor applications add it explicitly. See the observability sections of Spring Integration and Ktor Integration.

Testing

Module	Provides
storm-test	@StormTest JUnit 5 extension and SqlCapture, framework-free
storm-spring-boot-test-autoconfigure	The @DataStormTest Spring Boot test slice (test scope)

See Testing and Testing with @DataStormTest.

Module Overview

The following diagram shows how Storm's modules relate to each other. You only need the modules relevant to your language and integration choices.

storm-foundation (base interfaces)
└── storm-kotlin / storm-java21 (your primary dependency)
    ├── storm-kotlin-spring / storm-spring (Spring Framework)
    │   └── storm-kotlin-spring-boot-starter / storm-spring-boot-starter
    ├── storm-ktor (Ktor)
    │   └── storm-ktor-test (testing support)
    ├── dialect modules (postgresql, mysql, mariadb, oracle, mssqlserver, sqlite, h2)
    └── JSON modules (jackson2, jackson3, kotlinx-serialization)

Next Steps

With Storm installed, you are ready to define your first entity and run your first query:

• First Entity -- define an entity, create an ORM template, insert and fetch a record
• First Query -- custom queries, repositories, and type-safe filtering