Blog/Three abstractions

Three abstractions and nothing else

Framework complexity is easy to mistake for capability, and the parts of a model you cannot keep in your head tend to show up later in a debugger. ST/ORM has three user-facing concepts, and together they cover the whole framework.

February 17, 2026Design4 min read

Entity

An entity is the data your application works with: a Kotlin data class or a Java record with a couple of annotations, @PK for the primary key and @FK for a foreign key. ST/ORM maps entities to tables and columns by convention, so further annotations only appear where the convention does not fit. An entity has no hidden state and no behavior. It is database-backed data as a plain value.

Repository

A repository gives you CRUD operations and type-safe queries for one entity. You define an interface and write the bodies of its query methods with the DSL. ST/ORM does not parse a method name like findByStatusAndCreatedAtAfter into a hidden query, and there is no generated query you have to reverse-engineer from a log. Any query a repository runs is one you wrote and can read.

SQL Template

SQL templates give you direct SQL with type-safe binding and result mapping, for the cases where the DSL is the wrong tool: joins, reports, database-specific features, or queries that should stay SQL. A template sits beside the DSL rather than under it, and using one is an ordinary design choice. Type references and metamodel columns keep it checked, and parameters are bound automatically. The reasoning behind it is in keeping SQL in view rather than hiding it.

Why a small model is the point

There is more underneath, of course: transactions, a static metamodel, change detection, generated code. All of it exists to support these three concepts, and none of it adds a fourth one you have to learn.

The three follow one rule, which is that what happens can be seen in the code. No query runs that you did not write, the SQL each one produces is predictable, relationships load when you ask for them, and transaction boundaries are declared instead of inferred. That makes the model something you can teach a new engineer in an afternoon, and you never have to reconstruct what the framework decided to do on your behalf.