API reference › @evolu/common › local‑first/Schema › Mutation

type Mutation<S, Kind> = <TableName>(
  table: TableName,
  values: MutationValues<S[TableName], Kind>,
  options?: MutationOptions,
) => {
  id: InferOutput<S[TableName]["id"]>;
};

Defined in: packages/common/src/local-first/Schema.ts:194

Mutation function type. Accepts already-validated values — validation is the caller's responsibility using any Standard Schema library (Evolu Type, Zod, Valibot, ArkType, etc.).

Evolu does not use SQL for mutations to ensure data can be deterministically merged without conflicts. Explicit mutations also allow Evolu to automatically update SystemColumns and encourage developers to consider the number of changes produced, unlike SQL where a single query can inadvertently generate a large volume of CRDT messages. Each mutation produces exactly one CrdtMessage containing all provided columns.

Mutations never fail — values are already validated by the caller, and changes are stored locally in SQLite.

  • insert: all non-nullable columns required, nullable columns optional, id omitted (auto-generated)
  • update: only id required, everything else optional
  • upsert: like insert but id required too
Markdown for LLMs