Feature/storm 76 2 (#80)

Use fetchSize to limit memory consumption for large (streaming) results sets. (#76)

Author: zantvoort

README.md

@@ -13,7 +13,7 @@
 **Key benefits:**
 
 - **Minimal code**: Define entities with simple records/data classes and query with concise, readable syntax; no boilerplate.
-- **Parameterized by default**: String interpolations are automatically converted to bound parameters, making queries SQL injection safe by design.
+- **Parameterized by default**: String interpolations are automatically converted to bind variables, making queries SQL injection safe by design.
 - **Close to SQL**: Storm embraces SQL rather than abstracting it away, keeping you in control of your database operations.
 - **Type-safe**: Storm's DSL mirrors SQL, providing a type-safe, intuitive experience that makes queries easy to write and read while reducing the risk of runtime errors.
 - **Direct Database Interaction**: Storm translates method calls directly into database operations, offering a transparent and straightforward experience. It eliminates inefficiencies like the N+1 query problem for predictable and efficient interactions.

docs/index.md

@@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem';
 **Key benefits:**
 
 - **Minimal code**: Define entities with simple records/data classes and query with concise, readable syntax, no boilerplate.
-- **Parameterized by default**: String interpolations are automatically converted to bound parameters, making queries SQL injection safe by design.
+- **Parameterized by default**: String interpolations are automatically converted to bind variables, making queries SQL injection safe by design.
 - **Close to SQL**: Storm embraces SQL rather than abstracting it away, keeping you in control of your database operations.
 - **Type-safe**: Storm's DSL mirrors SQL, providing a type-safe, intuitive experience that makes queries easy to write and read while reducing the risk of runtime errors.
 - **Direct Database Interaction**: Storm translates method calls directly into database operations, offering a transparent and straightforward experience. It eliminates inefficiencies like the N+1 query problem for predictable and efficient interactions.

docs/testing.md

@@ -283,11 +283,11 @@ All three methods are scoped: only SQL statements generated within the block are
 
 Each captured statement is represented as a `CapturedStatement` record with three fields:
 
-| Field        | Type              | Description                                          |
-|--------------|-------------------|------------------------------------------------------|
+| Field        | Type              | Description                                                                     |
+|--------------|-------------------|---------------------------------------------------------------------------------|
 | `operation`  | `Operation`       | The SQL operation type: `SELECT`, `INSERT`, `UPDATE`, `DELETE`, or `UNDEFINED`. |
-| `statement`  | `String`          | The SQL text with `?` placeholders for bound parameters. |
-| `parameters` | `List<Object>`    | The bound parameter values in order.                 |
+| `statement`  | `String`          | The SQL text with `?` placeholders for bind variables.                          |
+| `parameters` | `List<Object>`    | The bound parameter values in order.                                            |
 
 Query the capture results using `count()`, `statements()`, or their filtered variants:
 

storm-core/src/main/java/st/orm/core/template/SqlDialect.java

@@ -467,4 +467,30 @@ default boolean useCatalogAsSchema() {
         return false;
     }
 
+    /**
+     * Returns the default JDBC fetch size hint for queries.
+     *
+     * <p>The returned value is passed to {@link PreparedStatement#setFetchSize(int)} to control how many rows the
+     * JDBC driver fetches from the database at a time. A value of {@code 0} (the default) leaves the fetch size
+     * unset, deferring to driver defaults.</p>
+     *
+     * @return the default fetch size.
+     * @since 1.10
+     */
+    default int defaultFetchSize() {
+        return 0;
+    }
+
+    /**
+     * Returns whether the default fetch size should only be applied for streaming result consumption
+     * (i.e., {@code getResultStream()} and flow-based access), not for eager methods like
+     * {@code getResultList()} or {@code getSingleResult()}.
+     *
+     * @return {@code true} if fetch size should only apply to streaming access.
+     * @since 1.10
+     */
+    default boolean streamOnlyFetchSize() {
+        return false;
+    }
+
 }

storm-core/src/main/java/st/orm/core/template/impl/PreparedQueryImpl.java

@@ -46,8 +46,10 @@ public PreparedQueryImpl(@Nonnull RefFactory refFactory,
                              @Nullable Class<? extends Data> affectedType,
                              boolean versionAware,
                              boolean managed,
+                             int defaultFetchSize,
+                             boolean streamOnlyFetchSize,
                              @Nonnull Function<Throwable, PersistenceException> exceptionTransformer) {
-        super(refFactory, ignore -> statement, bindVarsHandle, affectedType, versionAware, managed, false, exceptionTransformer);
+        super(refFactory, ignore -> statement, bindVarsHandle, affectedType, versionAware, managed, false, defaultFetchSize, streamOnlyFetchSize, exceptionTransformer);
         this.refFactory = refFactory;
         this.statement = statement;
         this.bindVarsHandle = bindVarsHandle;

storm-core/src/main/java/st/orm/core/template/impl/PreparedStatementTemplateImpl.java

@@ -178,6 +178,9 @@ private static TemplateProcessor createDataSourceProcessor(@Nonnull DataSource d
                     preparedStatement = transactionContext.getDecorator(PreparedStatement.class)
                             .decorate(preparedStatement);
                 }
+                if (!dialect.streamOnlyFetchSize() && dialect.defaultFetchSize() != 0) {
+                    preparedStatement.setFetchSize(dialect.defaultFetchSize());
+                }
                 if (bindVariables == null) {
                     setParameters(preparedStatement, parameters, dialect);
                 } else {
@@ -229,6 +232,9 @@ private static TemplateProcessor createConnectionProcessor(@Nonnull Connection c
                     preparedStatement = transactionContext.getDecorator(PreparedStatement.class)
                             .decorate(preparedStatement);
                 }
+                if (!dialect.streamOnlyFetchSize() && dialect.defaultFetchSize() != 0) {
+                    preparedStatement.setFetchSize(dialect.defaultFetchSize());
+                }
                 if (bindVariables == null) {
                     setParameters(preparedStatement, parameters, dialect);
                 } else {
@@ -492,13 +498,16 @@ public Query create(@Nonnull TemplateString template) {
         try {
             var sql = sqlTemplate().process(template);
             var bindVariables = sql.bindVariables().orElse(null);
+            SqlDialect dialect = providerFilter != null
+                    ? getSqlDialect(providerFilter, config)
+                    : getSqlDialect(config);
             return new QueryImpl(refFactory, unsafe -> {
                 try {
                     return templateProcessor.process(sql, unsafe);
                 } catch (SQLException e) {
                     throw new PersistenceException(e);
                 }
-            }, bindVariables == null ? null : bindVariables.getHandle(), sql.affectedType().orElse(null), sql.versionAware(), false, getExceptionTransformer(sql));
+            }, bindVariables == null ? null : bindVariables.getHandle(), sql.affectedType().orElse(null), sql.versionAware(), false, false, dialect.defaultFetchSize(), dialect.streamOnlyFetchSize(), getExceptionTransformer(sql));
         } catch (SqlTemplateException e) {
             throw new PersistenceException(e);
         }

storm-core/src/main/java/st/orm/core/template/impl/QueryImpl.java

@@ -38,7 +38,9 @@
 import java.time.ZoneOffset;
 import java.time.ZonedDateTime;
 import java.util.Calendar;
+import java.util.List;
 import java.util.Objects;
+import java.util.Optional;
 import java.util.TimeZone;
 import java.util.UUID;
 import java.util.function.Function;
@@ -67,14 +69,16 @@ class QueryImpl implements Query {
     private final Class<? extends Data> affectedType;
     private final boolean unsafe;
     private final boolean managed;
+    private final int defaultFetchSize;
+    private final boolean streamOnlyFetchSize;
     private final Function<Throwable, PersistenceException> exceptionTransformer;
 
     QueryImpl(@Nonnull RefFactory refFactory,
               @Nonnull Function<Boolean, PreparedStatement> statement,
               @Nullable BindVarsHandle bindVarsHandle,
               boolean versionAware,
               @Nonnull Function<Throwable, PersistenceException> exceptionTransformer) {
-        this(refFactory, statement, bindVarsHandle, null, versionAware, false, false, exceptionTransformer);
+        this(refFactory, statement, bindVarsHandle, null, versionAware, false, false, 0, false, exceptionTransformer);
     }
 
     QueryImpl(@Nonnull RefFactory refFactory,
@@ -83,7 +87,7 @@ class QueryImpl implements Query {
               boolean versionAware,
               boolean unsafe,
               @Nonnull Function<Throwable, PersistenceException> exceptionTransformer) {
-        this(refFactory, statement, bindVarsHandle, null, versionAware, false, unsafe, exceptionTransformer);
+        this(refFactory, statement, bindVarsHandle, null, versionAware, false, unsafe, 0, false, exceptionTransformer);
     }
 
     QueryImpl(@Nonnull RefFactory refFactory,
@@ -93,7 +97,7 @@ class QueryImpl implements Query {
               boolean versionAware,
               boolean unsafe,
               @Nonnull Function<Throwable, PersistenceException> exceptionTransformer) {
-        this(refFactory, statement, bindVarsHandle, affectedType, versionAware, false, unsafe, exceptionTransformer);
+        this(refFactory, statement, bindVarsHandle, affectedType, versionAware, false, unsafe, 0, false, exceptionTransformer);
     }
 
     QueryImpl(@Nonnull RefFactory refFactory,
@@ -104,13 +108,28 @@ class QueryImpl implements Query {
               boolean managed,
               boolean unsafe,
               @Nonnull Function<Throwable, PersistenceException> exceptionTransformer) {
+        this(refFactory, statement, bindVarsHandle, affectedType, versionAware, managed, unsafe, 0, false, exceptionTransformer);
+    }
+
+    QueryImpl(@Nonnull RefFactory refFactory,
+              @Nonnull Function<Boolean, PreparedStatement> statement,
+              @Nullable BindVarsHandle bindVarsHandle,
+              @Nullable Class<? extends Data> affectedType,
+              boolean versionAware,
+              boolean managed,
+              boolean unsafe,
+              int defaultFetchSize,
+              boolean streamOnlyFetchSize,
+              @Nonnull Function<Throwable, PersistenceException> exceptionTransformer) {
         this.refFactory = refFactory;
         this.statement = statement;
         this.bindVarsHandle = bindVarsHandle;
         this.versionAware = versionAware;
         this.affectedType = affectedType;
         this.managed = managed;
         this.unsafe = unsafe;
+        this.defaultFetchSize = defaultFetchSize;
+        this.streamOnlyFetchSize = streamOnlyFetchSize;
         this.exceptionTransformer = exceptionTransformer;
     }
 
@@ -128,7 +147,7 @@ class QueryImpl implements Query {
      */
     @Override
     public PreparedQuery prepare() {
-        return MonitoredResource.wrap(new PreparedQueryImpl(refFactory, statement.apply(unsafe), bindVarsHandle, affectedType, versionAware, managed, exceptionTransformer));
+        return MonitoredResource.wrap(new PreparedQueryImpl(refFactory, statement.apply(unsafe), bindVarsHandle, affectedType, versionAware, managed, defaultFetchSize, streamOnlyFetchSize, exceptionTransformer));
     }
 
     /**
@@ -139,7 +158,7 @@ public PreparedQuery prepare() {
      */
     @Override
     public Query managed() {
-        return new QueryImpl(refFactory, statement, bindVarsHandle, affectedType, versionAware, true, unsafe, exceptionTransformer);
+        return new QueryImpl(refFactory, statement, bindVarsHandle, affectedType, versionAware, true, unsafe, defaultFetchSize, streamOnlyFetchSize, exceptionTransformer);
     }
 
     /**
@@ -150,13 +169,23 @@ public Query managed() {
      */
     @Override
     public Query unsafe() {
-        return new QueryImpl(refFactory, statement, bindVarsHandle, affectedType, versionAware, managed, true, exceptionTransformer);
+        return new QueryImpl(refFactory, statement, bindVarsHandle, affectedType, versionAware, managed, true, defaultFetchSize, streamOnlyFetchSize, exceptionTransformer);
+    }
+
+    private QueryImpl withoutFetchSize() {
+        return new QueryImpl(refFactory, statement, bindVarsHandle, affectedType, versionAware, managed, unsafe, 0, false, exceptionTransformer);
     }
 
     private PreparedStatement getStatement() {
         return statement.apply(unsafe);
     }
 
+    private void applyFetchSize(@Nonnull PreparedStatement statement) throws SQLException {
+        if (defaultFetchSize != 0) {
+            statement.setFetchSize(defaultFetchSize);
+        }
+    }
+
     protected boolean closeStatement() {
         return true;
     }
@@ -186,6 +215,7 @@ public Stream<Object[]> getResultStream() {
             PreparedStatement statement = getStatement();
             boolean close = true;
             try {
+                applyFetchSize(statement);
                 ResultSet resultSet = statement.executeQuery();
                 try {
                     int columnCount = resultSet.getMetaData().getColumnCount();
@@ -240,6 +270,7 @@ public <T> Stream<T> getResultStream(@Nonnull Class<T> type) {
         boolean close = true;
         try {
             try {
+                applyFetchSize(statement);
                 ResultSet resultSet = statement.executeQuery();
                 int columnCount = resultSet.getMetaData().getColumnCount();
                 var mapper = getObjectMapper(columnCount, type, refFactory)
@@ -289,6 +320,62 @@ public <T extends Data> Stream<Ref<T>> getRefStream(@Nonnull Class<T> type, @Non
                 .map(pk -> pk == null ? null : interner.intern(refFactory.create(type, pk)));
     }
 
+    @Override
+    public Object[] getSingleResult() {
+        return streamOnlyFetchSize && defaultFetchSize != 0
+                ? withoutFetchSize().getSingleResult()
+                : Query.super.getSingleResult();
+    }
+
+    @Override
+    public <T> T getSingleResult(@Nonnull Class<T> type) {
+        return streamOnlyFetchSize && defaultFetchSize != 0
+                ? withoutFetchSize().getSingleResult(type)
+                : Query.super.getSingleResult(type);
+    }
+
+    @Override
+    public Optional<Object[]> getOptionalResult() {
+        return streamOnlyFetchSize && defaultFetchSize != 0
+                ? withoutFetchSize().getOptionalResult()
+                : Query.super.getOptionalResult();
+    }
+
+    @Override
+    public <T> Optional<T> getOptionalResult(@Nonnull Class<T> type) {
+        return streamOnlyFetchSize && defaultFetchSize != 0
+                ? withoutFetchSize().getOptionalResult(type)
+                : Query.super.getOptionalResult(type);
+    }
+
+    @Override
+    public List<Object[]> getResultList() {
+        return streamOnlyFetchSize && defaultFetchSize != 0
+                ? withoutFetchSize().getResultList()
+                : Query.super.getResultList();
+    }
+
+    @Override
+    public <T> List<T> getResultList(@Nonnull Class<T> type) {
+        return streamOnlyFetchSize && defaultFetchSize != 0
+                ? withoutFetchSize().getResultList(type)
+                : Query.super.getResultList(type);
+    }
+
+    @Override
+    public <T extends Data> List<Ref<T>> getRefList(@Nonnull Class<T> type, @Nonnull Class<?> pkType) {
+        return streamOnlyFetchSize && defaultFetchSize != 0
+                ? withoutFetchSize().getRefList(type, pkType)
+                : Query.super.getRefList(type, pkType);
+    }
+
+    @Override
+    public long getResultCount() {
+        return streamOnlyFetchSize && defaultFetchSize != 0
+                ? withoutFetchSize().getResultCount()
+                : Query.super.getResultCount();
+    }
+
     protected void close(@Nonnull ResultSet resultSet, @Nonnull PreparedStatement statement) {
         try {
             try {

storm-core/src/test/java/st/orm/core/spi/FetchSizeSqlDialectProviderImpl.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2024 - 2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package st.orm.core.spi;
+
+import jakarta.annotation.Nonnull;
+import st.orm.StormConfig;
+import st.orm.core.template.SqlDialect;
+
+/**
+ * Test dialect provider that returns a non-zero default fetch size.
+ * Ensures the fetch size code paths in PreparedStatementTemplateImpl and QueryImpl are exercised during tests.
+ */
+@Orderable.BeforeAny
+public class FetchSizeSqlDialectProviderImpl implements SqlDialectProvider {
+
+    @Override
+    public SqlDialect getSqlDialect(@Nonnull StormConfig config) {
+        return new DefaultSqlDialect(config) {
+            @Override
+            public String name() {
+                return "FetchSizeTest";
+            }
+
+            @Override
+            public int defaultFetchSize() {
+                return 100;
+            }
+        };
+    }
+}