
# 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

```text
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`](locks.md) | yes | yes | |
| `queries` | the SQL of [`@Query`](query.md) | no | yes | |
| `functions` | [`@Procedure`](database-functions.md) (database functions) | no | on PostgreSQL | `FunctionDataStore` |
| `changes` | [streams of changes](changes.md) | yes | no | `ChangeStreamDataStore` |

A store of another package has its own row: the `supabase` store of [spring_boot_starter_supabase](../spring-boot-starter-supabase/data.md) 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.

```properties
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`).

```dart
@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:

- `@UseStore` or `@UseDataSource` on the repository;
- `spring.data.store` in `application.yml` or `application.properties` (the file without a profile);
- the first described store whose `defaultWhen` holds.

What else follows:

- **A `@Transactional` on any bean** (without a `transactionManager:`) is a build error when the application's default store is described without transactions.
- **A capability that depends on the database** (`functions` of the SQL store) is declared `true` and 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.
- `@DataStoreDeclaration` on anything but a constant `DataStoreDescriptor` is 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:

```dart
@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`](json-columns.md) 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

```dart
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

- [Repositories](repositories.md)
- [Database functions](database-functions.md)
- [Changes of rows](changes.md)
- [Locks](locks.md)
- [All properties](properties.md)
- [The generator and data](../spring-core-dart-generator/data.md)
- [Supabase: data](../spring-boot-starter-supabase/data.md)
