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:
- its
@UseStore('name'); - the SQL store, with a
@UseDataSource; spring.data.store(memory,jdbc, or the name of any other store), when it is set;jdbcwith a primary data source, andmemorywithout.
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:
@UseStoreor@UseDataSourceon the repository;spring.data.storeinapplication.ymlorapplication.properties(the file without a profile);- the first described store whose
defaultWhenholds.
What else follows:
- A
@Transactionalon any bean (without atransactionManager:) is a build error when the application's default store is described without transactions. - A capability that depends on the database (
functionsof the SQL store) is declaredtrueand decided at startup: the build must not refuse what may work. - A store nothing describes is checked at startup only, as is a repository whose store the build cannot tell.
@DataStoreDeclarationon anything but a constantDataStoreDescriptoris a build error.
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.