Skip to content

Repository

A RIDDL repository is an abstraction for anything that can retain information (e.g. messages) for retrieval at a later time. This might be a relational database, NoSQL database, a data lake, an API, or something not yet invented. There is no specific technology implied other than the retention and retrieval of information. Thinking of repositories only as a database is missing the mark.

Schemas

As part of their intrinsic definition, repositories have schemas. Schemas in implementation and leaves them unspecified. Repository schemas in RIDDL have little relationship to SQL because they are not relational databases and indeed must support the schema for any kind of data storage. The schema is specified more like a graph database. A set of types defines what can be placed in the database, an optional set of links defines how the fields of those types are related, and a set of indices defines which fields the database indexes.

A repository may define multiple schemas, each with its own kind. The kind of schema may be: flat, relational, time-series, graphical, hierarchical, star, document, columnar, vector, or other. These are only suggestive of the kind of storage layout the repository uses — but riddlc warns about a few shapes that contradict the kind, such as a graphical schema with no links (repo-graph-no-links) or a flat one with several data entries (repo-flat-schema-many-nodes). The language reference lists all eight.

repository CartRepository is {
  schema CartData is relational
    of cart as record Cart
    of items as record CartItem
    link cartItems as field CartItem.id to field Product.id
    index on field Cart.id
}

A queried repository with no index at all

A repository that answers on query clauses but whose schemas declare no index draws a CompletenessWarning (repo-queried-without-index): a store queried without any index is a sequential scan by construction.

It is a warning and not an Error because the model may be under-specified rather than self-contradictory — the author may know the table is small. It stays silent for a ??? stub, a repository with no schema, and a write-only repository that answers no queries.

The check does not name which field to index, and that is a limit of what models say rather than caution: a repository's on query body is prose by design, so nothing in the model states which field the query filters on.

as type T is strict — changed in RIDDL 2.0

The clause says as type, so T must genuinely be a Type. A path that lands on an Entity, or on anything else, is an Error even though it parses.

This check previously never ran. Turning it on produced 202 errors across 186 of the 187 models in riddl-models — nearly the whole corpus — every one of them a clause that had been relying on a check that did nothing. If a schema of yours suddenly errors here, that is why.

The fix is usually to point at the record that describes the stored shape, rather than at the entity that owns it.

Handling Messages

A repository has a handler that processes messages with respect to the repository's stored information.

Query messages sent to the repository are requests for retrieval of some information. The handler should define how the processing of that query should proceed and yield a Result message.

Command messages sent to the repository are updates to the repository. The handler should define how the update works and may optionally yield an Event message but generally that is handled at a higher level of abstraction.

A repository is never changed by an event. An inlet that carries one is an Error (repo-inlet-carries-event), and an on event clause draws a Warning (handler-repository-handles-events). Have a projector or an entity turn the event into a command and send that. A repository with content but no handler at all draws repo-no-handler.

Ordering and Concurrency

A repository is a processor, so it handles messages one at a time — but the "one" is an entity, not the whole repository.

  • Queries always run concurrently. They change nothing, so the worst a concurrent read can do is see slightly old data, and the cure for that is to ask again.
  • Writes about ONE entity are applied one at a time, in arrival order. The create happens before the updates, and two updates to the same order never interleave.
  • Writes about DIFFERENT entities run concurrently. There is no total order across a repository. An implementation that serializes every write is not being more careful; it is imposing an order the model never asked for, and charging every unrelated write for it.

A write names its entity by the first field of its message typed Id(entity E). If a message carries several such fields, the first one declared decides which entity's sequence the write joins. A write message carrying none names no entity and so has no order at all. A code generator should say so rather than quietly pick one.

entity Order is { ??? }
entity Customer is { ??? }

// Ordered with the other writes about the same `order`. `customer` is also
// an Id, but it comes second, so it does not decide the ordering.
command RecordShipment is {
  order: Id(entity Order),
  customer: Id(entity Customer),
  carrier: String
}

option available: the CAP choice

A distributed store cannot be consistent, available and partition-tolerant all at once — that is the CAP theorem. Partitions happen whether you plan for them or not, so the real choice is what to give up while one is in progress:

During a partition Write ordering
Default Stays consistent — may refuse or delay a write it cannot order Per entity, as above
option available Keeps operating — gives up consistency Whatever the storage engine's transactions provide

An available repository asks its implementation to aim for continuous operation: handle failures where they happen, and restart only when there is truly no alternative. The entity option of the same name makes the same choice for an entity.

repository Clickstream is { ??? } with {
  option is available
  briefly as "Losing order between visits beats losing the visits"
}

This is a ruling for implementations

riddlc does not check any of this; none of it changed validation. It is what RIDDL's computational model requires of anything that generates a repository from a model, as clarified with the 2.6.0 release. A generator must keep per-entity ordering under the default and must not invent a total order across entities.

Repositories at Domain Scope

A repository normally lives in a Context. But a repository that synthesizes messages from entities across several contexts, and is queried by several contexts, belongs to the Domain instead — putting it inside any one context would misrepresent who owns it.

domain Commerce is {
  repository SalesData is { ??? }   // reaches Orders, Catalog and Shipping

  context Orders   is { ??? }
  context Catalog  is { ??? }
  context Shipping is { ??? }
}

Scope validation

A repository's reach is the set of contexts owning the messages its on clauses handle.

  • Error (repo-domain-scope-misplaced) — a domain-scoped repository reaching only ONE context. It is provably unnecessary at domain scope; move it into that context. Zero resolvable contexts means an incomplete model rather than proof, so that draws nothing.
  • CompletenessWarning (repo-handles-foreign-contexts) — a context-scoped repository reaching another context. Consider promoting it to domain scope.

Options

transient marks a repository whose contents are not durably persisted — a cache-like store. available and consistent choose a side of the CAP trade-off, as described above; consistent is the default and need not be written. batch (1 argument), microservice and protocol are also accepted.

Occurs In

Contains

flowchart TD
    Repository(["Repository"]) --> Schema
    Repository --> PC["Processor contents"]
    Schema --> SchemaParts["data · link · index"]