Set Up Your Project

This page is about getting Storm into a real project: what it needs from your toolchain, which of the four setup routes fits your situation, and how to prove the wiring works before you write application code.

Just want to see it work?

The Quickstart takes about five minutes, needs no database server, and ends with a working query and the SQL it generated. It is the fastest way to judge Storm, and it is the recommended first stop. Come back here when you are setting up a project you intend to keep.

Prerequisites

Requirement	Version
JDK (Kotlin path)	21 or later
JDK (Java path)	21 exactly; preview class files are version-locked
Kotlin (if using Kotlin)	2.0 or later
Build tool	Maven 3.9+ or Gradle 8+ (Gradle 8.5+ for the Storm plugin)
Database	Any JDBC-compatible database

Kotlin users need no preview flags. Java users must enable --enable-preview on compilation, tests, and execution, and must build and run on a JDK 21 toolchain. Installation covers both in full, including the exact Maven and Gradle configuration.

The JDK 21 pin is a property of the platform, not of Storm: the Java API is built on String Templates (JEP 430), a preview feature, and preview class files only load on the JDK that compiled them. When the JDK ships a stable successor, the Java API drops the preview flags and the version pin and stands alongside Kotlin as a first-class path. String Templates covers where that stands today, and which modules are affected (only storm-java21; the core framework and the Kotlin API are not).

Choose a Setup Route

All four routes end at the same place: a project with the Storm dependencies, the metamodel processor, and the Kotlin compiler plugin wired up.

Gradle plugin

Gradle plugin (recommended for Kotlin)

One plugin application imports the BOM, adds the core dependencies, wires the metamodel processor through KSP, selects the compiler-plugin variant matching your Kotlin version, and sets the Java preview flags.

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

Add the dialect module and JDBC driver for your database, and you are done. See Installation for the plugin's configuration options and the per-Kotlin-version matrix.

Maven BOM

Maven BOM

Import the BOM once, then declare Storm modules without version numbers. The metamodel annotation processor is added to the compiler plugin's annotationProcessorPaths, and the Java path needs --enable-preview.

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

See Installation for the full pom.xml, including the processor and preview-flag configuration.

Template repository

Start from a template

Each example application is a GitHub template with the build, schema, entities, and tests already wired. Click Use this template to generate a repository, then replace the sample entities with your own:

• Kotlin + Ktor
• Kotlin + Spring Boot
• Java + Spring Boot

The full set, with what each one demonstrates, is on the example projects page.

AI-assisted

AI-assisted setup

If you work with an AI coding tool (Claude Code, Cursor, GitHub Copilot, Windsurf, or Codex), one command installs Storm's rules and skills for it and can connect it to your development database:

npx @storm-orm/cli init

The tool can then add the dependencies, generate entities from your existing tables, and write repository methods. It has Storm's documentation and, with the MCP server configured, your real schema.

See AI-Assisted Development for the full setup and Database and MCP for the schema-aware server.

Verify the Wiring

Two checks catch almost every setup mistake before it reaches application code.

Does the metamodel generate? After a build, a User entity should have a generated User_ alongside it. If it does not, the annotation processor (Java) or KSP (Kotlin) is not on the compile path. See Metamodel for how generation is configured per build tool.

Do the entities match the database? Schema validation compares every mapped entity against the live schema and reports missing tables, missing columns, type mismatches, and nullability disagreements in one pass. validateSchemaOrThrow() fails loudly; validateSchema() returns the findings as a list so you can assert on them:

Kotlin

dataSource.orm.validateSchemaOrThrow()

Java

ORMTemplate.of(dataSource).validateSchemaOrThrow();

Run it at startup in development, or as a test. Schema Validation covers what is checked, how to scope it to specific entities, and the strict mode.

Next

With the project wired, work through the model:

1. First Entity -- define entities, insert and fetch records
2. First Query -- filtering, repositories, and streaming
3. Entities -- annotations, nullability, naming conventions

Integrating with a framework instead? Go straight to Spring Integration or Ktor Integration, which cover dependency injection, transaction management, and configuration for each.

The full map of the documentation, including paths for migrating from JPA and for evaluating Storm in production, is on the introduction page.

Stuck on the setup, or something here did not match what you saw? Ask in Discord or open a discussion.