You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/entities.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -736,7 +736,9 @@ record Order(@PK Integer id,
736
736
737
737
## Suppressing Schema Validation
738
738
739
-
Use `@DbIgnore` to suppress [schema validation](configuration.md#schema-validation) for an entity or a specific field. This is useful for legacy tables, columns handled by [custom converters](converters.md), or known type mismatches that are safe at runtime.
739
+
To suppress constraint-specific warnings (missing primary key, foreign key, or unique constraint), use the `constraint` attribute on `@PK`, `@FK`, or `@UK`. This is more targeted than `@DbIgnore` because it only suppresses the constraint check while preserving all other validation (column existence, type compatibility, nullability). See [Constraint Validation](validation.md#constraint-validation) for details and examples.
740
+
741
+
Use `@DbIgnore` to suppress [schema validation](configuration.md#schema-validation) for an entity or a specific field entirely. This is useful for legacy tables, columns handled by [custom converters](converters.md), or known type mismatches that are safe at runtime.
| Non-nullable entity field mapped to a nullable database column | `NULLABILITY_MISMATCH` | Warning |
80
+
| Entity declares `@PK` but the database has no primary key constraint | `PRIMARY_KEY_MISSING` | Warning |
79
81
| `@UK` field has a matching unique constraint in the database | `UNIQUE_KEY_MISSING` | Warning |
80
82
| `@FK` field has a matching foreign key constraint in the database | `FOREIGN_KEY_MISSING` | Warning |
81
83
@@ -85,16 +87,60 @@ Schema validation compares your entity and projection definitions against the ac
85
87
86
88
#### Constraint Validation
87
89
88
-
The `UNIQUE_KEY_MISSING` and `FOREIGN_KEY_MISSING` checks verify that the database has the constraints your entity model declares. These are warnings rather than errors because the ORM functions correctly without database-level enforcement: queries return the same results, inserts and updates succeed, and keyset pagination works as expected.
90
+
Schema validation checks that the database has the constraints your entity model declares. There are two categories of constraint findings:
91
+
92
+
**Mismatches (errors)** occur when a constraint exists in the database but contradicts the entity definition. For example, if `@FK val city: City` expects a foreign key referencing the `city` table, but the database has a foreign key on that column referencing the `account` table, that is a `FOREIGN_KEY_MISMATCH`. Similarly, if the entity declares `@PK` with columns `(id)` but the database primary key is `(user_id, role_id)`, that is a `PRIMARY_KEY_MISMATCH`. Mismatches are always hard errors because they indicate a bug in the entity definition.
93
+
94
+
**Missing constraints (warnings)** occur when the database has no constraint at all for a declared `@PK`, `@FK`, or `@UK` field. These are warnings rather than errors because the ORM functions correctly without database-level enforcement: queries return the same results, inserts and updates succeed, and keyset pagination works as expected.
89
95
90
96
However, database constraints serve as a safety net that the application layer cannot replace:
91
97
98
+
- **Primary key constraints** ensure row uniqueness at the database level. Without one, duplicate primary key values could be inserted by other applications or direct SQL.
92
99
- **Unique constraints** protect against application bugs and concurrent modifications that could insert duplicate values. Without a database-level unique constraint, a `@UK` field might contain duplicates that go undetected until a `findBy` call unexpectedly returns multiple results.
93
100
- **Foreign key constraints** protect referential integrity. Without a database-level foreign key constraint, orphaned rows can accumulate when referenced rows are deleted.
94
101
95
-
In [strict mode](#strict-mode), these warnings are promoted to errors, causing validation to fail if the constraints are missing. Use `@DbIgnore` to suppress these warnings for fields where the missing constraint is intentional (for example, when using application-level deduplication or soft deletes that make database constraints impractical).
102
+
##### Suppressing Constraint Warnings
103
+
104
+
When the database intentionally omits a constraint (for performance, for views, or because integrity is enforced at the application level), use the `constraint` attribute to suppress the warning for that specific field:
105
+
106
+
<Tabs groupId="language">
107
+
<TabItem value="kotlin" label="Kotlin" default>
108
+
109
+
```kotlin
110
+
// No FK constraint for performance reasons.
111
+
data class Order(
112
+
@PK val id: Int = 0,
113
+
@FK(constraint = false) val customer: Customer
114
+
) : Entity<Int>
115
+
116
+
// No unique index in the database.
117
+
data class User(
118
+
@PK val id: Int = 0,
119
+
@UK(constraint = false) val email: String
120
+
) : Entity<Int>
121
+
```
122
+
123
+
</TabItem>
124
+
<TabItem value="java" label="Java">
125
+
126
+
```java
127
+
// No FK constraint for performance reasons.
128
+
record Order(@PK Integer id,
129
+
@FK(constraint = false) Customer customer
130
+
) implements Entity<Integer> {}
131
+
132
+
// No unique index in the database.
133
+
record User(@PK Integer id,
134
+
@UK(constraint = false) String email
135
+
) implements Entity<Integer> {}
136
+
```
137
+
138
+
</TabItem>
139
+
</Tabs>
140
+
141
+
Setting `constraint = false` only suppresses the "missing" warning. If the database *does* have a constraint that contradicts the entity definition (a mismatch), it is always reported as a hard error regardless of this flag.
96
142
97
-
Use `@DbIgnore` to exclude entity fields from schema validation. See [Entities](entities.md) for annotation details.
143
+
In [strict mode](#strict-mode), missing constraint warnings are promoted to errors, causing validation to fail. The `constraint = false` flag takes precedence: fields marked with it are excluded from validation even in strict mode.
"No primary key constraint found in table '%s', but entity defines primary key columns %s. If intentional, use @PK(constraint = false) to suppress this check."
"No foreign key constraint found on column '%s' in table '%s' referencing table '%s'. If intentional, use @FK(constraint = false) to suppress this check."
0 commit comments