Stores and their capabilities

A repository talks to a DataStore: the in-memory store, the SQL store (JdbcDataStore), or one another package registers under its @UseStore name. Every store finds and saves aggregates. What a store has beyond that, it says in its capabilities, and a repository that uses more fails when it is created, with the method, the store and the fix.

Why

Stores differ. A store over a REST API has no transaction to join and no row to lock; a SQLite database has no functions; a SQL database does not report the changes of its rows. Without a declared list, a @Lock on such a store would be silently ignored, or fail at the first call in production. With it, the application does not start, and the message says what to do.

Example

Invalid repository StockRepository:
  - StockRepository.findBySku: @Lock needs a store with row locks, and the
    rest store is none: use a SQL store (@UseStore('jdbc') with
    spring.datasource.url), or remove @Lock (a @Version checks concurrent
    writes without a lock)

Every problem of a repository is in the same list.

The capabilities

Capability Used by Memory SQL Interface of the store
transactions @Transactional, the atomic writes of a repository yes yes TransactionalDataStore
locks @Lock yes yes
queries the SQL of @Query no yes
functions @Procedure (database functions) no on PostgreSQL FunctionDataStore
changes streams of changes yes no ChangeStreamDataStore

A store of another package has its own row: the supabase store of spring_boot_starter_supabase has functions, and changes with Realtime, and none of the first three.

The store of a repository

The first that applies:

  1. its @UseStore('name');
  2. the SQL store, with a @UseDataSource;
  3. spring.data.store (memory, jdbc, or the name of any other store), when it is set;
  4. jdbc with a primary data source, and memory without.
spring.data.store=memory

A name no store has fails the repositories when they are created, with the stores there are.

What is checked

When a repository is created, each thing it uses is compared with its store:

The repository has Needs Without it
@Lock on a method locks "use a SQL store, or remove @Lock (a @Version checks concurrent writes without a lock)"
@Transactional on the interface transactions "use a SQL store, or remove @Transactional and do the atomic work in one database function (@Procedure)"
@Query queries "set spring.datasource.url and add a driver, or write a derived query"
@Procedure functions "use a store whose database has them (PostgreSQL), or write the work as repository calls"
a stream of changes changes "use a store that does (the memory store), or return a Future and query again when the data may have changed"

A capability can depend on the database: the SQL store has functions with PostgreSQL and not with SQLite, and says so when the application starts.

Checked by the build

A package describes its store to the build with a constant in (or exported by) its lib/spring_auto_configuration.dart. The starter describes memory and jdbc the same way (memoryStore, jdbcStore).

@DataStoreDeclaration()
const documentStore = DataStoreDescriptor(
  'documents',
  capabilities: DataStoreCapabilities(changes: true),
  // The default store when the application's application.yml (without a
  // profile) sets every `whenProperty` and none of `unlessProperty`.
  defaultWhen: DataStoreDefault(
    whenProperty: ['documents.url'],
    unlessProperty: ['spring.datasource.url', 'spring.data.store'],
  ),
  // The store's own fix for what it lacks, said before the general one.
  fixes: {
    DataStoreCapability.transactions:
        'set documents.sql-url to keep the documents in SQL',
  },
);

When the build knows the store of a repository and the store is described, the error above is a build error, in the list of the repository's problems. The build knows the store from:

What else follows:

A store of your own

DataStore has the member DataStoreCapabilities get capabilities. Everything is false unless said, so a store declares what it has:

@override
DataStoreCapabilities get capabilities =>
    const DataStoreCapabilities(transactions: true, locks: true);
For The store also implements
transactions TransactionalDataStore: transactionManager, the manager the repositories and @DataTest use.
functions FunctionDataStore: callFunction(name, arguments).
changes ChangeStreamDataStore: changes(entity, criteria:) and filtersChanges(entity, criteria).
rows in the form of its database RowReadingDataStore: valueReader and readAggregates, used to read the results of @Procedure.
what of an entity it cannot keep EntityCheckingDataStore: mappingProblems(entity), asked when a repository is created; the SQL store refuses a Map, List or Set without @Json there. DataStoreDescriptor(collectionsNeedJson: true) asks the build for the same check.

This is a breaking change for a store written before: it must add capabilities.

In code

Future<void> refreshTotals(DataStore store) async {
  if (store.capabilities.functions && store is FunctionDataStore) {
    await store.callFunction('refresh_totals', const {});
  }
}

store.capabilities.supports(DataStoreCapability.locks);   // the same, by the enum

DataStoreCapability is the enum (transactions, locks, queries, functions, changes); each value carries the words of its error (usedBy, need, fix). A StoreRequirement(method, capability) is what one method needs; RepositoryFactory.operations(requirements:) takes them.

In Spring (Java)

No counterpart. Spring Data has a module for each store, and a feature a module lacks (a @Lock in Spring Data Redis) does not exist there at all.

See also