Scheme class base

A description of a configurable part of a database schema.

The "scheme" concept, as used in this library, is a configurable part of a full database schema. That is, an SQLite database managed by this library has a schema split into two parts:

  • The first part is the unchangeable foundation, which consists of the mapping table and the scheme table. The mapping table holds all application-supplied key-value data in the mandatory keyid and value columns; it also always includes the kind virtual column. The scheme table holds the overall scheme version of the second part of the schema.
  • The second part is a configurable extension, which consists of additional virtual columns for the mapping table, partial indexes for those virtual columns, FTS indexes for application-supplied key-value data from the mapping table, and a JSON path to extract a Kind from any JSON value stored in the value column of the mapping table.

A scheme's description is defined by an application via the following properties of the Scheme class: revision, kindPath, virtualColumns, partialIndexes, and searchIndexes. Changes in a scheme's description trigger the migration procedure of the corresponding database schema parts upon the first run of a new application build.

A scheme migration updates the database schema to reflect the new scheme configuration while leaving application-supplied key-value data intact. By increasing the Scheme.revision number, custom processing that modifies key-value data or performs other input-output operations can be added to a migration via Scheme.upgrader.

The overall scheme version, returned by the toDefinition function, is used by the library to track changes in the scheme's description. A scheme migration is triggered when the overall scheme version changes, which occurs when at least one of the following conditions is met, with the following consequences for each condition:

  • the revision increases — this causes Scheme.upgrader to be called;
  • the kindPath changes — this causes the rebuilding of the kind virtual column, its partial index, as well as all application-defined virtual columns, partial indexes, and search indexes;
  • the virtualColumns changes — this causes the rebuilding of changed virtual columns and their partial indexes, the creation of new columns, and the removal of deleted columns;
  • the partialIndexes changes — this causes the rebuilding of changed partial indexes, the creation of new indexes, and the removal of deleted indexes;
  • the searchIndexes changes — this causes the rebuilding of changed search indexes, the creation of new indexes, and the removal of deleted indexes.

Changes in SearchRowGetter implementations are not tracked automatically; see SearchIndex.getters for more information.

See also: VirtualColumn, PartialIndex, and SearchIndex.

Annotations
  • @immutable

Constructors

Scheme({int revision = schemeInitialRevision, DatabaseUpgrader? upgrader, String kindPath = standardKindPath, VirtualColumns virtualColumns = const [], PartialIndexes partialIndexes = const [], SearchIndexes searchIndexes = const []})
Creates a description of a scheme using the given parameters.

Properties

hashCode → int
The hash code for this object.
no setterinherited
kindPath → String
The JSON path to extract Kinds from database JSON values.
final
partialIndexes → PartialIndexes
A list of the partial index descriptions.
final
revision → int
The application-provided revision number for this scheme description.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
searchIndexes → SearchIndexes
A list of the FTS index descriptions.
final
upgrader → DatabaseUpgrader?
The callbacks invoked during scheme migration.
final
virtualColumns → VirtualColumns
A list of the virtual column descriptions.
final

Methods

elementsDefinition(List<SchemeElement> elements) → Map<String, Object>
Returns a map representing the overall version of the elements.
getPartialIndex(String name) → PartialIndex
Finds a PartialIndex with the given name.
getSearchIndex(String name) → SearchIndex
Finds a SearchIndex with the given name.
getVirtualColumn(String name) → VirtualColumn
Finds a VirtualColumn with the given name.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDefinition() → StdMap
Returns a JSON map representing the scheme's overall version.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

kKindPath → const String
The key for the kindPath part of the overall scheme version map.
kPartialIndexes → const String
The key for the partialIndexes part of the overall scheme version map.
kSchemaVersion → const String
The key for the schema version part of the overall scheme version map.
kSchemeRevision → const String
The key for the revision part of the overall scheme version map.
kSearchIndexes → const String
The key for the searchIndexes part of the overall scheme version map.
kVirtualColumns → const String
The key for the virtualColumns part of the overall scheme version map.