Keep up with what changed.

A current result, a mutation history, and a meaningful application event are not the same thing. ShiverDB's design gives each a clear role, connected by committed state.

Three questions. Three useful answers.

QuestionConceptWhat it carries
What matches my query now?subscribeAn initial result and ordered committed deltas.
What records changed?changesDurable committed mutation history, followed with a cursor.
What happened in my application?emitA semantic event created inside a transaction.

The authoritative commit stream can supply all three without forcing them into one API or one retention model.

Follow a result, not a polling loop.

A subscription represents a maintained query result. Creation yields an initial snapshot, followed by ordered deltas from committed transactions after that snapshot.

Players in the current zoneShiverDB SQL
subscribe nearby_players as
select
  id,
  name,
  position
from player
where zone = :zone

This example assumes the table has position and zone fields. The engine may track dependencies, maintain results incrementally, or recompute them. Those are implementation strategies, not different visible meanings.

Only committed state is observable. A rolled-back mutation must never appear in the subscription. Interest in a result can also help the engine decide which records and fields to keep hot.

Pick up from a known point.

A changefeed exposes durable mutation history. A cursor identifies a monotonic position in that history so consumers can follow changes for audit, replay, synchronization, or analytics.

Read committed player changesShiverDB SQL
changes player since :cursor

Durable does not mean retained forever. Retention may be finite. A cursor older than the retained history must produce an explicit error, not an apparently complete result with missing changes.

Say what a transaction meant.

A mutation says that a field changed. An application event can say that an item was purchased. An emit statement belongs to the transaction that makes the change.

Inside a purchase routineShiverDB SQL
emit item_purchased {
  player = auth.player,
  item = item.id,
  price = item.price
}

The containing routine supplies item. Events become externally visible only after commit, preserve source-program order within a transaction, and disappear with a rollback.

Recording events in the same commit envelope avoids a separate manual outbox pattern inside the proposed engine. It does not promise exactly-once delivery to outside services or make external side effects transactional.

Use as much of the model as you need.

Generated clients may expose subscribed results as local typed relations. In that model, applications read subscribed local state and write by invoking routines. Schema metadata can describe record types, routine calls, events, and structured errors.

Conventional applications can still issue direct SQL. Routines, subscriptions, graph relations, policies, and generated bindings are optional at the application level.

Safe routine retries require preserved arguments and reconstructable transaction-visible inputs, with no external effects. External routines need explicit transaction boundaries. A reactive interface does not erase these requirements.

Next: put the concepts together

From the specifications

This guide explains the design. The original documents carry the precise requirements and recommendations.