diff --git a/docs/configuration.md b/docs/configuration.md index c2c56d061..33c38088b 100644 --- a/docs/configuration.md +++ b/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`. diff --git a/docs/ktor-integration.md b/docs/ktor-integration.md index d7f523d9b..c6c873662 100644 --- a/docs/ktor-integration.md +++ b/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. diff --git a/docs/queries.md b/docs/queries.md index 2f40ea036..755cd4960 100644 --- a/docs/queries.md +++ b/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,7 +53,7 @@ val exists: Boolean = orm.existsBy(User_.email, email) -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); @@ -61,15 +61,14 @@ var users = orm.entity(User.class); // Find by ID Optional user = users.findById(userId); -// Find all matching -List usersInCity = users.select() - .where(User_.city, EQUALS, city) - .getResultList(); +// Find one by a field value +Optional byEmail = users.findBy(User_.email, email); -// Find first matching -Optional user = users.select() - .where(User_.email, EQUALS, email) - .getOptionalResult(); +// Find all matching a field value +List usersInCity = users.findAllBy(User_.city, city); + +// Find all whose field matches any of several values (WHERE ... IN) +List 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 = users.findById(userId); -// Find with predicate -Optional user = users.select() - .where(User_.email, EQUALS, email) - .getOptionalResult(); +// Find one by a field value +Optional byEmail = users.findBy(User_.email, email); -// Find all matching -List 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 usersInCity = users.findAllBy(User_.city, city); -// Exists +// Count and exists +long count = users.count(); boolean exists = users.existsById(userId); ``` diff --git a/docs/spring-integration.md b/docs/spring-integration.md index 5f20b907e..022ce70a3 100644 --- a/docs/spring-integration.md +++ b/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. diff --git a/docs/validation.md b/docs/validation.md index c2727900b..5084cfd8e 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -321,7 +321,7 @@ 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) ``` @@ -329,14 +329,14 @@ 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 | diff --git a/website/versioned_docs/version-1.12.0/configuration.md b/website/versioned_docs/version-1.12.0/configuration.md index c2c56d061..33c38088b 100644 --- a/website/versioned_docs/version-1.12.0/configuration.md +++ b/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`. diff --git a/website/versioned_docs/version-1.12.0/ktor-integration.md b/website/versioned_docs/version-1.12.0/ktor-integration.md index d7f523d9b..c6c873662 100644 --- a/website/versioned_docs/version-1.12.0/ktor-integration.md +++ b/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. diff --git a/website/versioned_docs/version-1.12.0/queries.md b/website/versioned_docs/version-1.12.0/queries.md index 2f40ea036..755cd4960 100644 --- a/website/versioned_docs/version-1.12.0/queries.md +++ b/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,7 +53,7 @@ val exists: Boolean = orm.existsBy(User_.email, email) -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); @@ -61,15 +61,14 @@ var users = orm.entity(User.class); // Find by ID Optional user = users.findById(userId); -// Find all matching -List usersInCity = users.select() - .where(User_.city, EQUALS, city) - .getResultList(); +// Find one by a field value +Optional byEmail = users.findBy(User_.email, email); -// Find first matching -Optional user = users.select() - .where(User_.email, EQUALS, email) - .getOptionalResult(); +// Find all matching a field value +List usersInCity = users.findAllBy(User_.city, city); + +// Find all whose field matches any of several values (WHERE ... IN) +List 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 = users.findById(userId); -// Find with predicate -Optional user = users.select() - .where(User_.email, EQUALS, email) - .getOptionalResult(); +// Find one by a field value +Optional byEmail = users.findBy(User_.email, email); -// Find all matching -List 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 usersInCity = users.findAllBy(User_.city, city); -// Exists +// Count and exists +long count = users.count(); boolean exists = users.existsById(userId); ``` diff --git a/website/versioned_docs/version-1.12.0/spring-integration.md b/website/versioned_docs/version-1.12.0/spring-integration.md index 5f20b907e..022ce70a3 100644 --- a/website/versioned_docs/version-1.12.0/spring-integration.md +++ b/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. diff --git a/website/versioned_docs/version-1.12.0/validation.md b/website/versioned_docs/version-1.12.0/validation.md index c2727900b..5084cfd8e 100644 --- a/website/versioned_docs/version-1.12.0/validation.md +++ b/website/versioned_docs/version-1.12.0/validation.md @@ -321,7 +321,7 @@ 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) ``` @@ -329,14 +329,14 @@ 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 |