1.14.0

[zantvoort]

A quality release: a smaller, more coherent API, and SQL that is correct on every dialect Storm supports rather than on the permissive ones, held there by a Technology Compatibility Kit that every dialect runs.

Requires Java 21+ and Kotlin 2.0+.

Added

• A join widens the query (A join widens the query: replace the Any variants with root widening #371): from the join onward every clause accepts paths from any entity in the query, so referencing a joined table needs no separate method. widen() and narrow(rootType) make the two directions explicit, widen() admitting short-form references on a query that joins nothing and narrow restoring the root for the operations defined relative to it, resultGroupedBy and scroll. A path on an entity the query does not carry fails when the query is built, naming the entity, the root, and the paths that pin the table where it appears more than once.
• A grouping states an identity (Grouping by an entity should mean one row per that entity, whatever columns the dialect needs #491, The dialect renders an identity grouping, so callers never write per-database groupings #492), and the generator emits the columns that express it. groupBy(User_.city) emits GROUP BY c.id on PostgreSQL, MySQL, SQLite and H2, and every column of the referenced key on SQL Server and Oracle, which do not resolve functional dependency from a key. The relationship, the key beyond it, the root's own key and a reference all state the same identity; any other path groups by its value. Selecting an entity selects the tables its foreign keys reach, so a grouping covers those keys too, and since every foreign key is to-one this cannot move a row into a different group.
• Every dialect runs the same Technology Compatibility Kit (Dialect conformance suite: one shared repository test suite run per dialect, instead of seven copies #514). The new build-time storm-dialect-tck module holds 146 conformance tests over entity repository, polymorphic, schema validation and multi-column expression behavior, and all seven dialects run all four of them; the seven per-dialect copies of EntityRepositoryTest fall from 13,931 lines to 2,498, and the other three per-dialect files are gone. Fourteen behaviors used to run on H2 alone, the most permissive dialect in the set, among them the key chains where a key is a reference the mapper has to flatten rather than a column. Where dialects legitimately differ they state a capability once (supportsSequences, supportsFetchWithSequences, supportsBatchUpsertAndFetchWithSequences, supportsRowValueIn, supportsRowValueComparison) and pin their own statement text, with a drift guard that fails naming any statement a dialect can reach but has not pinned. A dialect that cannot do something demonstrates that it refuses cleanly rather than being silently exempt. Consolidating surfaced coverage gaps that had gone unnoticed: MariaDB ran 10 of 16 multi-column expression tests, SQL Server skipped 12 sequence tests it passes, and Oracle's schema init masked failures behind continue-on-error. The module is build-time only and is not published.
• A placeholder swallowed by a string literal is refused (fix: refuse a placeholder swallowed by a string literal #528). A value interpolated inside quotes renders as the literal text '?', which is valid SQL, so the value binds to the position of the next placeholder and every parameter after it shifts; where the leftover count balances, the statement runs against the wrong arguments and returns results that look ordinary. A statement that binds more positional parameters than it exposes placeholders is now refused when it is built, naming the cause and the SQL, and the Kotlin compiler plugin reports it in the editor where it is written. The check reads the compiled SQL once per cached statement shape and only walks it when the SQL contains a quote at all; more placeholders than parameters stays legal, since that is bind vars.
• The slow statement log (Slow statement log: report individual slow executions under st.orm.sql.slow #517): each execution whose database time exceeds a threshold reports under st.orm.sql.slow at WARN, carrying the statement, the rows, and how the execution compares to what its shape typically costs (typically 6.0 ms, 306x) and binds (parameters 32 (typically 3)), which says whether to look at the parameters or at the query. storm.sql-log.slow.threshold=200ms in Spring, sqlLogSlowThreshold in Ktor, storm.sql_log.slow.threshold on a plain JVM. Values render at TRACE only, lines are rate-limited per shape, and the threshold derives from the performance log when it has none of its own, so the derived default names the statement behind a warning instead of adding warnings of its own.
• The SQL log is retunable while the application runs (Slow statement log: report individual slow executions under st.orm.sql.slow #517): SlowStatementLog.threshold(Duration) and limit(int) land on the next execution, and the performance log reads its settings per unit of work. Where the actuator is on the class path, the storm endpoint reads and sets both halves (GET / POST /actuator/storm), Storm's control surface rather than the SQL log's. Only enabled stays a startup decision, since it installs the request filter and the entry-point proxies.
• @StormTest and @DataStormTest run on the database the application deploys on (Run @StormTest against a real database with Testcontainers #502): database = POSTGRESQL (or MYSQL, MARIADB, MSSQL_SERVER, ORACLE) starts a Testcontainers-managed container once per JVM and gives each test class a freshly created database inside it, with image overriding the pinned default. The database's Testcontainers 2 module and JDBC driver stay out of storm-test's dependencies, and a test that names a container database fails naming both when one is missing. TestDatabase.POSTGRESQL.container() exposes the shared container, and createDatabase() a database of your own.
• @StormTest runs each test inside a database transaction that is rolled back afterwards (Per-test rollback for @StormTest #387), so tests no longer observe each other's writes. Transaction blocks demarcate with savepoints inside it; rollback = false opts a class out.
• OrmTemplateFactory in the Spring Boot starters (feat: property-driven template composition for Spring Boot and Ktor #520): one bean that composes a fully integrated ORMTemplate wherever the application defines its own template beans. Failure translation follows storm.exception-translation.enabled per data source, observations resolve their conventions from each data source's JDBC URL and report the template's name as storm.database, and a customize block applies application-specific composition without touching the integration SPI.
• The Ktor plugin closes its composition gaps against the starters (feat: property-driven template composition for Spring Boot and Ktor #520): storm.observations.semanticConventions = otel selects the OpenTelemetry conventions per database, and a customize slot applies composition after the integration is wired, inherited per named database unless it sets its own. Observer composition is shared with the starters through QueryObservers in storm-micrometer, so the two stacks cannot drift.
• Storm-initiated transactions run through a JtaTransactionManager (Run Storm-initiated transactions through a JTA transaction manager #504) where no resource-bound manager claims the data source, alongside JdbcTransactionManager and a JpaTransactionManager backed by it. An option a manager refuses is reported against the option passed to the block.
• manualCommitConnections() (Support DataSources that hand out manual-commit connections #450): a template declares that its DataSource hands out connections with auto-commit already disabled, and the non-transactional paths manage auto-commit accordingly. A connection that arrives with auto-commit disabled without the declaration fails naming the two possible causes and the fix.
• The and and or combinators root at their operands' least common root (feat: root the and/or combinators at the operands' least common root #519), so a cross-root conjunction is one clause rather than an escalation to whereBuilder { }. On a narrow builder the combination is unsatisfiable and is rejected at the call site, at compile time; on a widened builder it solves to the common supertype and defers to the query-build validation, exactly like consecutive where() clauses.
• StormConfig.sqlShapingKeys() (Derive the shape-affecting config keys instead of hand-maintaining TEMPLATE_SHAPE_KEYS #405) exposes the configuration keys whose values affect the generated SQL, and the template cache key includes exactly these.
• The select { } and delete { } blocks add the remaining clause forms (Bring the select { } block up to parity with the chained builder #397): where(records), where(path, records), where(path, operator, values), whereRef(path, refs) and the descending order template. whereRef works inside whereBuilder { } too. narrow, widen and typedId stay outside the block by design.

Changed

• The engine leaves the application's compile classpath (refactor: keep the engine off the application compile classpath #527). storm-core is provided on the library modules and runtime on the Spring Boot starters, so completion and imports offer exactly one EntityRepository, one ORMTemplate, one QueryBuilder: the facade's. A project that follows the installation guide (implementation on the facade, runtimeOnly("st.orm:storm-core")) is unaffected; one that relied on the engine arriving transitively adds the runtime dependency explicitly. Creating a template without the engine on the runtime classpath names the missing st.orm:storm-core dependency instead of surfacing as a NoClassDefFoundError at the first statement. On the module path the facades require storm-foundation transitively; storm.core stays non-transitive.
• The integration contract moves to st.orm.spi in storm-foundation (refactor: keep the engine off the application compile classpath #527): ExceptionMapper, ExceptionContext, SqlOperation, QueryObserver, QueryContext, StatementOrigin, SqlCommenter and the cursor codecs; SqlTemplateException joins PersistenceException in st.orm. Implementations update their imports, and META-INF/services/st.orm.core.spi.CursorCodecProvider renames to st.orm.spi.CursorCodecProvider. Transaction bridging, RefFactory and the dialect surface stay engine SPI in storm-core. QueryObserver.onTransaction receives the st.orm.TransactionOptions an application passes to transaction(options) { }, and @StormTest injects SchemaValidation rather than the engine's validator, keeping test classpaths engine-free.
• typed(pkType) is renamed typedId(pkType) (A join widens the query: replace the Any variants with root widening #371): it types the erased primary-key parameter, where narrow types the root. fetch(...) comes right after select(), before any join, enforced at compile time. Kotlin's select { } and delete { } blocks are widened from the start, return the widened builder, and carry the chained builder's clause vocabulary.
• The SQL log is configured per log and named after the two loggers it writes to (Slow statement log: report individual slow executions under st.orm.sql.slow #517): storm.sql-log.performance.* for the performance log (st.orm.sql.perf), which says what a unit of work cost the database, and storm.sql-log.slow.* for the slow statement log (st.orm.sql.slow), which names the execution that cost too much. The old flat keys are removed rather than mapped, so a configuration still on storm.sql-log.enabled binds to nothing and starts with the performance log off and no message. The Ktor DSL, the HOCON keys, the system properties and the Spring types follow: StormPerformanceLogFilter and StormPerformanceLogEntryPointPostProcessor. Database time is measured to the statement's return everywhere, so the summary, SqlCapture.duration and the slow line agree.
• The public API is JSpecify null-marked (Adopt JSpecify on the public API surface #418), and the jakarta annotations are gone from Storm's signatures, so jakarta.annotation-api is no longer a dependency. JSpecify itself is optional: compilers and analysis tools read the annotations from bytecode. Kotlin callers get real T / T? types where the Java surface used to be platform types, and the generated nullable metamodel chain compiles on Kotlin 2.1+ (Kotlin 2.1+ consumers cannot compile generated metamodels against the null-marked API #458).
• Projection<ID>'s type argument is a checked contract instead of a phantom parameter (Projection's ID type parameter is phantom and carries two meanings #419): ID is the projection's row identity type, which for a foreign-key-typed primary key is the referenced table's key. Record validation rejects a declaration the record contradicts, and the rule that a foreign key must not be an auto-generated primary key applies to entities only.
• The implementation is sealed (Qualify the JPMS exports of the impl packages and move SqlLog's rendering internals out of the public class #395, storm-kotlin publishes internals: Flow operators collide with kotlinx.coroutines, factory top-levels leak #396): st.orm.core.template.impl and st.orm.core.repository.impl are exported to Storm's own modules only, and storm-kotlin's impl packages are internal throughout, including the Flow operators that collided with their kotlinx.coroutines namesakes. All five Kotlin modules compile in explicit API mode; the coroutine-aware SQL log recording the Ktor plugin shares is the one exception, behind @InternalStormApi.
• What a transaction block joins, and which blocks share a connection, follows from the block structure (REQUIRES_NEW on another data source inside a Storm block fails with Incompatible DataSource #505, Joining propagations inside NOT_SUPPORTED or NEVER join the non-transactional connection #507) rather than from what happens to be bound at the time. A REQUIRED block inside a NOT_SUPPORTED or NEVER block opens a transaction of its own, MANDATORY and NEVER are checked against the block the enclosing code declares, and data source consistency is checked per physical transaction, so an audit write can go to a second database from inside a transaction on the first.
• Transaction observations go through an observation convention, StormTransactionObservationConvention (Transaction observations bypass the Micrometer convention, and the Ktor delegating observer drops them entirely #400), the way query observations always did, and the Ktor plugin forwards them. Query observations carry the shape identity as the low-cardinality storm.shape key value, cached per compiled template; the identity uses the full 64 bits it is declared with and renders as sixteen hex digits.
• Both metamodel processors converge on one contract (Metamodel processors: the Java processor is non-incremental with weak error reporting, and KSP diverges from APT #411, Non-Ref FK cycles between entities generate a metamodel that fails at class initialization #412): they reject a cycle of non-Ref foreign keys at compile time naming the cycle and the fix, the Java processor generates the <Type>NullableMetamodel chain variant, and KSP sources components from the primary constructor, contributes abstract properties only for sealed interfaces, and escapes keyword-named properties. The Java processor registers with Gradle as an aggregating incremental processor, so attaching it no longer forces full recompilation, and the Gradle plugin wires it into every source set (Gradle plugin: test source sets get no metamodel, and the javadoc task misses the preview flag #415), so entities in test sources get a metamodel.
• The @DataStormTest slice imports every auto-configuration the starters register in production (@DataStormTest slice: repositories are unproxied and standard verification tools are missing #401), verified by a parity test, and provides JdbcTemplate, JdbcClient and Testcontainers service connection support.
• The Java and Kotlin facades close their remaining parity gaps (refactor: keep the engine off the application compile classpath #527). Kotlin's path-based where and whereRef clauses accept Navigable paths, so navigation-only nodes reached through a Ref compile in both languages; Java's where(path, record) bounds the record by Data. Kotlin's findRefBy drops two unused type parameters, findAllRefBy(field, values) accepts any value type, and Templates gains the named param(name, Calendar, TemporalType) variant. The two-argument selectFrom(fromType, selectType) renders the select list from the FROM table, so selectType may be any record shape over those columns.
• SqlLog carries the diagnostics API only (Qualify the JPMS exports of the impl packages and move SqlLog's rendering internals out of the public class #395): summary rendering lives in SqlLogRenderer and call-site capture in CallSiteCapture, both internal. The hydration shape is gone from summary rows; the per-type report belongs to storm analyze (storm analyze: one command for entity graph cost and the design budget #503).
• The deliberately paired artifacts (Guard the deliberately colliding artifact pairs with enforcer rules #384), storm-java21 / storm-kotlin, the two Spring Boot starters, storm-jackson2 / storm-jackson3 and the two metamodel processors, ship the same fully qualified names, one half per class path. Each half bans its twin through a maven-enforcer rule.
• @GenerateMetamodel moves to st.orm (@GenerateMetamodel is dead: both processors look for st.orm.GenerateMetamodel but the annotation lives in st.orm.core.template #378), where both processors can find it: the annotation processor module must not depend on storm-foundation.

Fixed

• getResultCount() counted the rows a select returned instead of executing a count query (getResultCount() streams and counts the full result set while its javadoc promises a count query #379). It now emits a real COUNT query and page totals are inferred from it.
• Grouping by a reference resolved to its own column rather than to the referenced table's key (fix: grouping by a reference names the referenced table's key #495). A grouping that determines nothing, such as selecting Pet while grouping by Pet_.owner, is refused when the query is built, on every dialect rather than only the ones that would notice.
• Storm-initiated transaction blocks failed to find a JpaTransactionManager (Storm-initiated transactions fail when a JpaTransactionManager is on the classpath #383). Matching is JPA-first, ambiguity fails fast naming the candidates, and the auto-configuration orders after the JDBC and Hibernate managers on Spring Boot 3 and 4.
• An explicitly set dialect was dropped back to discovery by withConfig, and discovery silently picked the first candidate (withConfig discards an explicitly set dialect, and getSqlDialect(StormConfig) resolves first-match #404). Resolution is lazy and reports the candidates by name.
• Static caches pinned classes, class loaders and data sources (Audit the unbounded static caches keyed by Class, Method, Constructor and DataSource #394), keeping redeployed applications alive. ClassValue, a class-loader-keyed cache and weak DataSource keys replace the strong static maps.
• Compiler-folded constant interpolations reached the SQL as text rather than as parameters (Compiler plugin silently leaves interpolations as SQL text when constant splitting bails #393), template keywords dispatched inside identifiers rather than on word boundaries and a nested WHERE was detected as top-level (SQL lexing edge cases: keyword detection without word boundaries, nested WHERE defeating the unsafe-statement check #391), and unknown interpolation-safety modes passed silently (Interpolation safety check: bypassed by one explicit t(), no else on the mode switch, mode name mismatch #392); the compiler plugin marker is now required.
• Metamodel.KeyDelegate.isNullable() always returned false through the documented factory (Metamodel.KeyDelegate.isNullable() is always false through the documented factory #403). Metamodel.key() wraps anything that is not already a Key, and the delegate's check tested for Key, so every factory-built delegate reported non-nullable; nullability now derives from the underlying field.
• The JSON converters shared one mapper cache across field types (JSON converter caches: field-type-blind cache key, dead sealed-subtype registration for containers, unbounded kotlinx cache #410), dropped the annotations Java propagates to a record component's backing field, accessor or constructor parameter, and wrote @Json fields with the runtime rather than the declared type, so a polymorphic value missed the discriminator that reading the column expects.
• The outer RefFactory was not restored after nested JSON deserialization (JSON converters: the RefFactory ThreadLocal is not reentrant, nested deserialization produces detached refs #385): three converters left the ThreadLocal pointing at the nested factory. A kotlinx @Contextual Ref target must itself be @Serializable.
• Compound primary key Ref objects failed to deserialize (Ref with a compound primary key serializes but cannot deserialize #390); the plain-object primary key path is gated on findRecordType.
• MariaDB sequences went undiscovered during schema validation (MariaDB: schema validation reports SEQUENCE_NOT_FOUND for every sequence #389), through an INFORMATION_SCHEMA.TABLES strategy gated on sequencesDiscovered.
• @StormTest shared one database across test classes (StormExtension: parallel-execution store collision, database-name collision, abstract-base breakage #386): a class-keyed store and a nanoTime-derived database name isolate them, and the annotation is @Inherited.
• SqlCapture lost statements across Kotlin coroutine boundaries and skipped an action that returns no row (SqlCapture cannot capture from Kotlin coroutines, and Kotlin lacks a blocking sqlLog #388, fix: SqlCapture captures an action that returns no row #490). run becomes record, storm-kotlin-test gains a blocking recording { } scope, and the Ktor test scope wires into the Setup phase so it captures for real.
• Ktor named databases did not inherit plugin-level configuration, an unclaimed named lookup passed silently, and the SQL log did not bind to application.conf (Ktor configuration gaps: named databases inherit almost nothing, sqlLog mutates JVM globals and has no config-file support #399); the plugin closed pools it did not create and failed on eager dependency-injection resolution (Ktor plugin lifecycle: closes user-supplied pools, requires HikariCP to shut down, eager DI resolution can abort startup #398).
• Unknown validation-mode values skipped schema validation with only a boot warning and silently escalated record validation (Validation modes: unknown values silently skip schema validation and silently escalate record validation #433). A typo now fails fast naming the accepted values.
• The slow log's per-shape rate limit skipped the executions it has no shape for (Slow statement log: report individual slow executions under st.orm.sql.slow #517), which is where a degraded database could flood it; those executions now share one reporting budget.
• Java record entities were missing from the type index and a missing type index passed unreported (Type index never records Java entities: the processor accepts CLASS but entities are records #377).
• Error messages and API docs named methods that exist on no surface (Error messages and API docs name methods that don't exist #406): template errors pointed at whereAny/whereAll builder methods and Kotlin KDoc called Java names such as getResultList(). A requireColumn guard replaces the phantom references.
• The PostgreSQL, MariaDB and MSSQL JDBC drivers leaked onto consumers' classpaths (PostgreSQL, MariaDB and MSSQL modules leak pinned JDBC drivers at compile scope #402), published POM metadata pointed at the wrong organization (Published POM metadata points at the old GitHub org and uses inconsistent contact addresses #416), and the CLI accepted unknown commands, swallowed the --dev argument and hid fetch failures (CLI: unknown commands fall into the setup wizard, --dev leaks its argument, failures report success #414).
• Unloading a ref that wraps an unsaved record failed with a NullPointerException (refactor: keep the engine off the application compile classpath #527) instead of an error naming the cause.

Removed

• whereAny, whereAnyRef, whereAnyBuilder, havingAny, groupByAny, orderByAny, orderByDescendingAny, andAny and orAny (A join widens the query: replace the Any variants with root widening #371): a join widens the query, so and / or inherit the query root and widen() covers the query that joins nothing.
• QueryTemplate.dialect() from the Java API (refactor: keep the engine off the application compile classpath #527): which dialect executes a query is engine configuration. It remains on the engine's own template surface.
• connectionProvider(...) and transactionTemplateProvider(...) from the facade builders (refactor: keep the engine off the application compile classpath #527). Bridging a transaction manager is framework-level composition, available as SpringOrmTemplate.builder(dataSource, beanFactory) and springOrmTemplateBuilder(dataSource, beanFactory), or on the engine builder directly.
• QueryBuilder.append (page(Pageable) runs a count query even when the fetched page determines the total #428, Remove QueryBuilder.append: raw trailing fragments bypass builder invariants #429) and hasOrderBy() (refactor: keep the engine off the application compile classpath #527) from the public API.
• jakarta.annotation-api as a dependency (Adopt JSpecify on the public API surface #418): the public API is JSpecify null-marked instead.
• The flat storm.sql-log.* keys (Slow statement log: report individual slow executions under st.orm.sql.slow #517), replaced by the performance and slow sections rather than mapped.

Upgrading

1. Recompile against 1.14.0.
2. Add the engine as a runtime dependency if it was arriving transitively: runtimeOnly("st.orm:storm-core"), or <scope>runtime</scope> in Maven. The Spring Boot starters and the Gradle plugin already do this for you.
3. Update st.orm.core.spi imports to st.orm.spi in any ExceptionMapper, QueryObserver, SqlCommenter or CursorCodecProvider implementation, and rename the CursorCodecProvider service file.
4. Replace the Any clause variants: whereAny(...) and friends become plain where(...) after a join, or widen().where(...) on a query that joins nothing. typed(pkType) becomes typedId(pkType), and fetch(...) moves to directly after select().
5. Rename the SQL log keys: storm.sql-log.enabled becomes storm.sql-log.performance.enabled, and the thresholds, limit, call sites, line width and entry points move under performance. The old keys bind to nothing and log no warning.
6. Review tests that relied on writes committing: @StormTest now rolls back each test, and rollback = false opts a class out.
7. Check code that reached into an impl package: the Kotlin impl surfaces are internal and the core impl packages are exported to Storm's own modules only.

Full changelog: v1.13.1...v1.14.0

---

This discussion was created from the release 1.14.0.