BoscaDeveloper Documentation

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.

kotlin
  • Use @Contextual on UUID fields 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:

kotlin

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.

kotlin

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 typeBehavior
List<T>Maps all rows to a list of model objects
T?Maps the first row, or returns null if no rows
TMaps the first row, throws if no rows
UnitExecutes 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:

kotlin

Batch Lookups

Use any(:ids) with a List parameter for batch lookups — a single SQL query with an array parameter:

kotlin
@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

OptionDefaultPurpose
returnUpdateCountfalseReturn the number of affected rows instead of mapping results
autoCloseResulttrueAutomatically close the result set after reading
autoCloseStatementtrueAutomatically 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.