Schema & Columns topic

Schema

Tables are declared as abstract final classes with static const columns. Using const means the very same TableColumn object is shared by the query builder (Users.age.gt(18)) and by derive annotations (@Column(Users.name)), since annotation arguments must be compile-time constants.

abstract final class Users extends TableRef<Users> {
  const Users._();

  static const id = PrimaryKey<int, Users>('id');
  static const name = ValueColumn<String, Users>('name');
  static const authorId = Ref<int, Users, Posts>('author_id');
}

The column hierarchy

TableColumn is sealed: every column is exactly one of

• ValueColumn — a plain column,
• PrimaryKey — the table's primary key,
• Ref — a foreign key, carrying its target table as a type parameter.

Being sealed lets the join API and codegen pattern-match on the column kind (e.g. to auto-derive FK-aware joins) and keeps the switch exhaustive as new column kinds are added.

Every TableColumn is also a Selection, so it can be read straight out of a row — see RowReader in Query Builder.

Table markers and sources

• TableRef — the un-aliased source for a table (from(Users)).
• TableAlias — an aliased source, used when the same table appears twice in one query (self-joins).
• Aggregate / RawSelection / ColumnValue — supporting selectable/assignable types used by aggregation, raw SQL escape hatches, and INSERT/UPDATE values.

Classes

Aggregate<T>

An aggregate over a column (or COUNT(*)), usable in select(...) and readable from a row via its readKey. Build with TableColumn.count, countAll, or the numeric aggregates (IntColumnAggregates).

ColumnValue<Tbl>

A column-scoped assignment (column = value) for INSERT/UPDATE. The value is already encoded; Tbl keeps it bound to its table.

PrimaryKey<T, Tbl>

A primary-key column.

RawSelection<T>

A raw, typed SQL selection (escape hatch): emitted verbatim in the projection and read back by its readKey (the raw as alias). Uses ? placeholders.

Ref<T, Tbl, Target>

A foreign-key column on Tbl that references the PrimaryKey of Target. Referencing the PK column object (a leaf) keeps it const-cycle free even for mutual foreign keys, and the shared T enforces matching key types.

TableAlias<Tbl>

An aliased table for self-joins (the same table joined more than once). Columns are rebound to the alias, so sender.col(Users.id) serializes as "sender"."id" and is distinct from recipient.col(Users.id).

TableColumn<T, Tbl>

A typed column belonging to table Tbl.

TableRef<Tbl>

Table descriptor: its name and full column list (the default projection for from/joins). Cycle-safe even with foreign keys because Ref points at a PrimaryKey leaf, not back at a TableRef.

ValueColumn<T, Tbl>

An ordinary value column.