docs: correct schema-mode default to fail and document Java field finders

docs/configuration.md

@@ -17,7 +17,7 @@ Storm can be configured through `StormConfig`, system properties, Spring Boot's
 | `storm.entity_cache.retention` | `default` | Cache retention mode: `default` or `light` |
 | `storm.template_cache.size` | `2048` | Maximum number of compiled templates to cache |
 | `storm.validation.record_mode` | `fail` | Record validation mode: `fail`, `warn`, or `none` |
-| `storm.validation.schema_mode` | `none` | Schema validation mode: `none`, `warn`, or `fail` (Spring Boot and Ktor) |
+| `storm.validation.schema_mode` | `fail` | Schema validation mode: `none`, `warn`, or `fail` (Spring Boot and Ktor) |
 | `storm.validation.strict` | `false` | Treat schema validation warnings as errors |
 | `storm.validation.interpolation_mode` | `warn` | Interpolation safety mode: `warn`, `fail`, or `none` (see [Interpolation Safety](#interpolation-safety)) |
 | `st.orm.scrollable.maxSize` | `1000` | Maximum window size allowed in a serialized cursor (system property only) |
@@ -88,7 +88,7 @@ storm:
     size: 2048
   validation:
     record-mode: fail
-    schema-mode: none
+    schema-mode: fail
     strict: false
 ```
 
@@ -112,7 +112,7 @@ storm {
     }
     validation {
         recordMode = "fail"
-        schemaMode = "none"
+        schemaMode = "fail"
         strict = false
     }
 }
@@ -759,4 +759,4 @@ java -Dstorm.validation.schema_mode=fail \
 - `storm.validation.schema_mode=fail` catches entity-to-schema mismatches at startup rather than at runtime.
 - `storm.validation.interpolation_mode=fail` prevents execution of templates that were not processed by the compiler plugin and do not use explicit `t()` calls, protecting against accidental SQL injection.
 
-During development, the defaults (`schema_mode=none`, `interpolation_mode=warn`) provide a smoother experience: schema validation is skipped (since the schema may be evolving), and missing compiler plugin usage is logged as a warning rather than blocking execution.
+In the Spring Boot starter and Ktor plugin, `schema_mode` already defaults to `fail`, so entity-to-schema mismatches abort startup out of the box; relax it to `warn` or `none` while a schema is still evolving. `interpolation_mode` defaults to `warn`, so missing compiler plugin usage is logged rather than blocking execution until you opt into `fail`.

docs/ktor-integration.md

@@ -530,7 +530,7 @@ See the [Spring Integration](spring-integration.md#template-decorator) section o
 
 ## Schema Validation
 
-Storm can validate entity definitions against the live database schema at startup. This catches common mapping errors (missing columns, type mismatches, nullability differences) before your application serves its first request. Configure the validation mode in the plugin or in `application.conf`:
+Storm can validate entity definitions against the live database schema at startup. This catches common mapping errors (missing columns, type mismatches, nullability differences) before your application serves its first request. Validation runs in `fail` mode by default; set it to `warn` or `none` in the plugin or in `application.conf` to relax it:
 
 ```kotlin
 install(Storm) {
@@ -550,9 +550,9 @@ storm {
 
 | Mode | Behavior |
 |------|----------|
-| `none` | Skip validation (default). Suitable for production when schemas are managed by migrations. |
-| `warn` | Log mismatches at startup without blocking. Recommended during development. |
-| `fail` | Block startup if any entity definitions do not match the database schema. Useful in CI/CD pipelines. |
+| `fail` | Block startup if any entity definitions do not match the database schema (default). |
+| `warn` | Log mismatches at startup without blocking. Useful while the schema is still evolving. |
+| `none` | Skip validation. Suitable when schemas are managed entirely by migrations. |
 
 See [Validation](validation.md) for details on what is validated and how to interpret the output.
 

docs/queries.md

@@ -19,11 +19,11 @@ Storm offers three ways to query data, each suited to different complexity level
 
 | Approach | Best for | Type safety | Flexibility |
 |----------|----------|-------------|-------------|
-| **Repository `findBy`** | Simple key lookups by primary key or unique key | Full compile-time | Low (single-field equality only) |
+| **Repository `findBy` / `findAllBy`** | Lookups by primary key or any single field | Full compile-time | Low (single-field equality or `IN`) |
 | **Query DSL** | Filtering, ordering, pagination with type-safe conditions | Full compile-time | Medium (AND/OR predicates, joins, ordering) |
 | **SQL Templates** | Complex joins, subqueries, CTEs, window functions, database-specific SQL | Column references checked at compile time, SQL structure at runtime | High (full SQL control) |
 
-Start with the simplest approach that meets your needs. Use `findBy` or `findAll` for straightforward lookups. Move to the query builder when you need compound filters or pagination. Use SQL templates when you need SQL features the DSL does not cover.
+Start with the simplest approach that meets your needs. Use `findById`, `findBy`, or `findAllBy` for straightforward lookups. Move to the query builder when you need compound filters or pagination. Use SQL templates when you need SQL features the DSL does not cover.
 
 ---
 
@@ -53,23 +53,22 @@ val exists: Boolean = orm.existsBy(User_.email, email)
 </TabItem>
 <TabItem value="java" label="Java">
 
-The Java DSL uses the same `EntityRepository` interface as Kotlin. Obtain a repository with `orm.entity(Class)` and use its fluent query builder. Return types use `Optional` for single results and `List` for collections.
+The Java repository exposes the same `EntityRepository` interface as Kotlin. Obtain it with `orm.entity(Class)`. Field-based finders (`findBy`, `findAllBy`, `getBy`) cover single-column lookups; the fluent query builder handles anything more complex. Return types use `Optional` for single results and `List` for collections.
 
 ```java
 var users = orm.entity(User.class);
 
 // Find by ID
 Optional<User> user = users.findById(userId);
 
-// Find all matching
-List<User> usersInCity = users.select()
-    .where(User_.city, EQUALS, city)
-    .getResultList();
+// Find one by a field value
+Optional<User> byEmail = users.findBy(User_.email, email);
 
-// Find first matching
-Optional<User> user = users.select()
-    .where(User_.email, EQUALS, email)
-    .getOptionalResult();
+// Find all matching a field value
+List<User> usersInCity = users.findAllBy(User_.city, city);
+
+// Find all whose field matches any of several values (WHERE ... IN)
+List<User> selected = users.findAllBy(User_.city, cities);
 
 // Count
 long count = users.count();
@@ -117,20 +116,17 @@ var users = orm.entity(User.class);
 // Find by ID
 Optional<User> user = users.findById(userId);
 
-// Find with predicate
-Optional<User> user = users.select()
-    .where(User_.email, EQUALS, email)
-    .getOptionalResult();
+// Find one by a field value
+Optional<User> byEmail = users.findBy(User_.email, email);
 
-// Find all matching
-List<User> usersInCity = users.select()
-    .where(User_.city, EQUALS, city)
-    .getResultList();
+// Require exactly one (throws if none, or if more than one)
+User owner = users.getBy(User_.email, email);
 
-// Count
-long count = users.count();
+// Find all matching a field value
+List<User> usersInCity = users.findAllBy(User_.city, city);
 
-// Exists
+// Count and exists
+long count = users.count();
 boolean exists = users.existsById(userId);
 ```
 

docs/spring-integration.md

@@ -504,11 +504,11 @@ storm:
   validation:
     skip: false
     warnings-only: false
-    schema-mode: none
+    schema-mode: fail
     strict: false
 ```
 
-The `schema-mode` property controls startup schema validation: `none` (default) skips validation, `warn` logs mismatches without blocking startup, and `fail` blocks startup if any entity definitions do not match the database schema. The `strict` property controls whether warnings (type narrowing, nullability mismatches) are treated as errors. See the [Configuration](configuration.md#schema-validation) guide for details.
+The `schema-mode` property controls startup schema validation: `fail` (default) blocks startup if any entity definitions do not match the database schema, `warn` logs mismatches without blocking startup, and `none` skips validation. The `strict` property controls whether warnings (type narrowing, nullability mismatches) are treated as errors. See the [Configuration](configuration.md#schema-validation) guide for details.
 
 See the [Configuration](configuration.md) guide for a description of each property and the full precedence rules.
 

docs/validation.md

@@ -321,22 +321,22 @@ When using the Spring Boot Starter, both record and schema validation can be con
 storm:
   validation:
     record-mode: fail   # or "warn" or "none" (default: fail)
-    schema-mode: none   # or "warn" or "fail" (default: none)
+    schema-mode: fail   # or "warn" or "none" (default: fail)
     strict: false       # treat schema warnings as errors (default: false)
 ```
 
 The `schema-mode` values:
 
 | Value | Behavior |
 |-------|----------|
-| `none` | Schema validation is skipped (default). |
+| `fail` | Mismatches cause startup to fail with a `PersistenceException` (default). |
 | `warn` | Mismatches are logged at WARN level; startup continues. |
-| `fail` | Mismatches cause startup to fail with a `PersistenceException`. |
+| `none` | Schema validation is skipped. |
 
 ### Configuration Properties
 
 | Property | Default | Description |
 |----------|---------|-------------|
 | `storm.validation.record_mode` | `fail` | Record validation mode: `fail`, `warn`, or `none` |
-| `storm.validation.schema_mode` | `none` | Schema validation mode: `none`, `warn`, or `fail` (Spring Boot only) |
+| `storm.validation.schema_mode` | `fail` | Schema validation mode: `none`, `warn`, or `fail` (Spring Boot and Ktor) |
 | `storm.validation.strict` | `false` | When `true`, schema validation warnings are treated as errors |

website/versioned_docs/version-1.12.0/configuration.md

@@ -17,7 +17,7 @@ Storm can be configured through `StormConfig`, system properties, Spring Boot's
 | `storm.entity_cache.retention` | `default` | Cache retention mode: `default` or `light` |
 | `storm.template_cache.size` | `2048` | Maximum number of compiled templates to cache |
 | `storm.validation.record_mode` | `fail` | Record validation mode: `fail`, `warn`, or `none` |
-| `storm.validation.schema_mode` | `none` | Schema validation mode: `none`, `warn`, or `fail` (Spring Boot and Ktor) |
+| `storm.validation.schema_mode` | `fail` | Schema validation mode: `none`, `warn`, or `fail` (Spring Boot and Ktor) |
 | `storm.validation.strict` | `false` | Treat schema validation warnings as errors |
 | `storm.validation.interpolation_mode` | `warn` | Interpolation safety mode: `warn`, `fail`, or `none` (see [Interpolation Safety](#interpolation-safety)) |
 | `st.orm.scrollable.maxSize` | `1000` | Maximum window size allowed in a serialized cursor (system property only) |
@@ -88,7 +88,7 @@ storm:
     size: 2048
   validation:
     record-mode: fail
-    schema-mode: none
+    schema-mode: fail
     strict: false
 ```
 
@@ -112,7 +112,7 @@ storm {
     }
     validation {
         recordMode = "fail"
-        schemaMode = "none"
+        schemaMode = "fail"
         strict = false
     }
 }
@@ -759,4 +759,4 @@ java -Dstorm.validation.schema_mode=fail \
 - `storm.validation.schema_mode=fail` catches entity-to-schema mismatches at startup rather than at runtime.
 - `storm.validation.interpolation_mode=fail` prevents execution of templates that were not processed by the compiler plugin and do not use explicit `t()` calls, protecting against accidental SQL injection.
 
-During development, the defaults (`schema_mode=none`, `interpolation_mode=warn`) provide a smoother experience: schema validation is skipped (since the schema may be evolving), and missing compiler plugin usage is logged as a warning rather than blocking execution.
+In the Spring Boot starter and Ktor plugin, `schema_mode` already defaults to `fail`, so entity-to-schema mismatches abort startup out of the box; relax it to `warn` or `none` while a schema is still evolving. `interpolation_mode` defaults to `warn`, so missing compiler plugin usage is logged rather than blocking execution until you opt into `fail`.

website/versioned_docs/version-1.12.0/ktor-integration.md

@@ -530,7 +530,7 @@ See the [Spring Integration](spring-integration.md#template-decorator) section o
 
 ## Schema Validation
 
-Storm can validate entity definitions against the live database schema at startup. This catches common mapping errors (missing columns, type mismatches, nullability differences) before your application serves its first request. Configure the validation mode in the plugin or in `application.conf`:
+Storm can validate entity definitions against the live database schema at startup. This catches common mapping errors (missing columns, type mismatches, nullability differences) before your application serves its first request. Validation runs in `fail` mode by default; set it to `warn` or `none` in the plugin or in `application.conf` to relax it:
 
 ```kotlin
 install(Storm) {
@@ -550,9 +550,9 @@ storm {
 
 | Mode | Behavior |
 |------|----------|
-| `none` | Skip validation (default). Suitable for production when schemas are managed by migrations. |
-| `warn` | Log mismatches at startup without blocking. Recommended during development. |
-| `fail` | Block startup if any entity definitions do not match the database schema. Useful in CI/CD pipelines. |
+| `fail` | Block startup if any entity definitions do not match the database schema (default). |
+| `warn` | Log mismatches at startup without blocking. Useful while the schema is still evolving. |
+| `none` | Skip validation. Suitable when schemas are managed entirely by migrations. |
 
 See [Validation](validation.md) for details on what is validated and how to interpret the output.
 

website/versioned_docs/version-1.12.0/queries.md

@@ -19,11 +19,11 @@ Storm offers three ways to query data, each suited to different complexity level
 
 | Approach | Best for | Type safety | Flexibility |
 |----------|----------|-------------|-------------|
-| **Repository `findBy`** | Simple key lookups by primary key or unique key | Full compile-time | Low (single-field equality only) |
+| **Repository `findBy` / `findAllBy`** | Lookups by primary key or any single field | Full compile-time | Low (single-field equality or `IN`) |
 | **Query DSL** | Filtering, ordering, pagination with type-safe conditions | Full compile-time | Medium (AND/OR predicates, joins, ordering) |
 | **SQL Templates** | Complex joins, subqueries, CTEs, window functions, database-specific SQL | Column references checked at compile time, SQL structure at runtime | High (full SQL control) |
 
-Start with the simplest approach that meets your needs. Use `findBy` or `findAll` for straightforward lookups. Move to the query builder when you need compound filters or pagination. Use SQL templates when you need SQL features the DSL does not cover.
+Start with the simplest approach that meets your needs. Use `findById`, `findBy`, or `findAllBy` for straightforward lookups. Move to the query builder when you need compound filters or pagination. Use SQL templates when you need SQL features the DSL does not cover.
 
 ---
 
@@ -53,23 +53,22 @@ val exists: Boolean = orm.existsBy(User_.email, email)
 </TabItem>
 <TabItem value="java" label="Java">
 
-The Java DSL uses the same `EntityRepository` interface as Kotlin. Obtain a repository with `orm.entity(Class)` and use its fluent query builder. Return types use `Optional` for single results and `List` for collections.
+The Java repository exposes the same `EntityRepository` interface as Kotlin. Obtain it with `orm.entity(Class)`. Field-based finders (`findBy`, `findAllBy`, `getBy`) cover single-column lookups; the fluent query builder handles anything more complex. Return types use `Optional` for single results and `List` for collections.
 
 ```java
 var users = orm.entity(User.class);
 
 // Find by ID
 Optional<User> user = users.findById(userId);
 
-// Find all matching
-List<User> usersInCity = users.select()
-    .where(User_.city, EQUALS, city)
-    .getResultList();
+// Find one by a field value
+Optional<User> byEmail = users.findBy(User_.email, email);
 
-// Find first matching
-Optional<User> user = users.select()
-    .where(User_.email, EQUALS, email)
-    .getOptionalResult();
+// Find all matching a field value
+List<User> usersInCity = users.findAllBy(User_.city, city);
+
+// Find all whose field matches any of several values (WHERE ... IN)
+List<User> selected = users.findAllBy(User_.city, cities);
 
 // Count
 long count = users.count();
@@ -117,20 +116,17 @@ var users = orm.entity(User.class);
 // Find by ID
 Optional<User> user = users.findById(userId);
 
-// Find with predicate
-Optional<User> user = users.select()
-    .where(User_.email, EQUALS, email)
-    .getOptionalResult();
+// Find one by a field value
+Optional<User> byEmail = users.findBy(User_.email, email);
 
-// Find all matching
-List<User> usersInCity = users.select()
-    .where(User_.city, EQUALS, city)
-    .getResultList();
+// Require exactly one (throws if none, or if more than one)
+User owner = users.getBy(User_.email, email);
 
-// Count
-long count = users.count();
+// Find all matching a field value
+List<User> usersInCity = users.findAllBy(User_.city, city);
 
-// Exists
+// Count and exists
+long count = users.count();
 boolean exists = users.existsById(userId);
 ```
 

website/versioned_docs/version-1.12.0/spring-integration.md

@@ -504,11 +504,11 @@ storm:
   validation:
     skip: false
     warnings-only: false
-    schema-mode: none
+    schema-mode: fail
     strict: false
 ```
 
-The `schema-mode` property controls startup schema validation: `none` (default) skips validation, `warn` logs mismatches without blocking startup, and `fail` blocks startup if any entity definitions do not match the database schema. The `strict` property controls whether warnings (type narrowing, nullability mismatches) are treated as errors. See the [Configuration](configuration.md#schema-validation) guide for details.
+The `schema-mode` property controls startup schema validation: `fail` (default) blocks startup if any entity definitions do not match the database schema, `warn` logs mismatches without blocking startup, and `none` skips validation. The `strict` property controls whether warnings (type narrowing, nullability mismatches) are treated as errors. See the [Configuration](configuration.md#schema-validation) guide for details.
 
 See the [Configuration](configuration.md) guide for a description of each property and the full precedence rules.
 

website/versioned_docs/version-1.12.0/validation.md

@@ -321,22 +321,22 @@ When using the Spring Boot Starter, both record and schema validation can be con
 storm:
   validation:
     record-mode: fail   # or "warn" or "none" (default: fail)
-    schema-mode: none   # or "warn" or "fail" (default: none)
+    schema-mode: fail   # or "warn" or "none" (default: fail)
     strict: false       # treat schema warnings as errors (default: false)
 ```
 
 The `schema-mode` values:
 
 | Value | Behavior |
 |-------|----------|
-| `none` | Schema validation is skipped (default). |
+| `fail` | Mismatches cause startup to fail with a `PersistenceException` (default). |
 | `warn` | Mismatches are logged at WARN level; startup continues. |
-| `fail` | Mismatches cause startup to fail with a `PersistenceException`. |
+| `none` | Schema validation is skipped. |
 
 ### Configuration Properties
 
 | Property | Default | Description |
 |----------|---------|-------------|
 | `storm.validation.record_mode` | `fail` | Record validation mode: `fail`, `warn`, or `none` |
-| `storm.validation.schema_mode` | `none` | Schema validation mode: `none`, `warn`, or `fail` (Spring Boot only) |
+| `storm.validation.schema_mode` | `fail` | Schema validation mode: `none`, `warn`, or `fail` (Spring Boot and Ktor) |
 | `storm.validation.strict` | `false` | When `true`, schema validation warnings are treated as errors |