Models & Repositories
Data classes, the @Repository annotation, SQL mapping, and query patterns.
Models
Models are @Serializable data classes living in core-* modules so both contracts and implementations can reference them.
- Use
@ContextualonUUIDfields for proper serialization context. - The Category insert omits
id, so its database default supplies the ID. Follow the owning table's ID convention when adding a model. - Keep models in the
core-*module, not the implementation module.
Input Types
Input types represent data coming from GraphQL mutations:
Repositories
Repository interfaces such as CategoryRepository use @Repository and @Query to declare SQL. KSP generates the JDBC implementation. Keep repositories in the implementation module and call them from services.
Named Parameters
SQL parameters use :paramName syntax. When passing a model object, parameter names match the object's properties — :name maps to category.name.
Map database columns explicitly
Result mapping uses model property names. Annotate snake_case columns with @ColumnName; for example, @ColumnName("profile_id") val profileId: UUID. Use a property-level @property:DbMapper with JsonbMapper for typed JSONB values. These annotations belong on the shared model.
Return Types
| Return type | Behavior |
|---|---|
List<T> | Maps all rows to a list of model objects |
T? | Maps the first row, or returns null if no rows |
T | Maps the first row, throws if no rows |
Unit | Executes the statement without reading results |
returning *
The returning * SQL clause causes the database to return the inserted/updated row. Combined with a model return type, this gives you the entity with database-generated fields:
Batch Lookups
Use any(:ids) with a List parameter for batch lookups — a single SQL query with an array parameter:
@Query functions accept a single model parameter alongside any number of primitive parameters. To pass data from two model objects, destructure into primitive parameters at the call site. @Query Options
| Option | Default | Purpose |
|---|---|---|
returnUpdateCount | false | Return the number of affected rows instead of mapping results |
autoCloseResult | true | Automatically close the result set after reading |
autoCloseStatement | true | Automatically close the prepared statement after execution |
An update or delete that returns an affected-row count must use @Query(..., returnUpdateCount = true). An integer return type alone does not select this behavior.
Register migrations
Add SQL migrations to the owning module and include each resource in its migration provider's list. Give the provider a name, following that module's existing convention. Creating an SQL file alone does not make it run at startup.