ToStore class

High-performance storage engine Features:

  • Chain operations
  • Multi-space architecture with global data tables
  • Supports multiple instances with isolated resources
  • Each instance has independent file storage, cache, index, and transactions

高性能数据存储引擎 特性：

  • 支持链式操作
  • 多空间架构设计，支持全局共享数据表
  • 支持多实例，资源完全隔离
  • 每个实例拥有独立的文件存储、缓存、索引和事务

Constructors

ToStore({String? dbPath, String? dbName, DataStoreConfig? config, List<TableSchema> schemas = const [], Future<void> onConfigure(ToStore db)?, Future<void> onCreate(ToStore db)?, Future<void> onOpen(ToStore db)?})
Create independent instances with different database paths dbPath Database root path. On Android/iOS: REQUIRED — provide a persistent app directory (e.g., using path_provider's getApplicationDocumentsDirectory()). On desktop/server: optional — if omitted, a standard OS application data directory will be used. dbName Database name for quickly creating different database instances (will be stored in dbPath/dbName/) config Database configuration schemas Database table schemas, Designed for mobile application scenarios, auto upgrade onConfigure Callback when configuring database onCreate Callback when database is first created onOpen Callback when database is opened
factory

Properties

config → DataStoreConfig
Get database configuration
no setter
currentSpaceName → String?
Get current space name
no setter
hashCode → int
The hash code for this object.
no setterinherited
instancePath → String?
Get the final storage path of the database instance.
no setter
kv → KvStore
Key-value storage namespace
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
status → DbStatus
Get unified status and diagnostics Returns a DbStatus object containing memory, space, table, config, and migration status information
no setter

Methods

backup({bool compress = true, BackupScope scope = BackupScope.currentSpaceWithGlobal}) → Future<String>
Create a backup of the database.
batchInsert(String tableName, List<Map<String, dynamic>> dataList, {bool allowPartialErrors = true}) → Future<DbResult>
Batch insert multiple records.
batchUpdate(String tableName, List<Map<String, dynamic>> dataList, {bool allowPartialErrors = true}) → Future<DbResult>
Batch update multiple records based on primary key.
batchUpsert(String tableName, List<Map<String, dynamic>> dataList, {bool allowPartialErrors = true}) → Future<DbResult>
Batch upsert multiple records based on unique constraints.
clear(String tableName) → Future<DbResult>
Clear all data in a table.
close({bool keepActiveSpace = true}) → Future<void>
Close database and clean up resources keepActiveSpace When false, clears active space so next launch uses default (e.g. logout). Default true.
createTable(TableSchema schema) → Future<DbResult>
Create a database table with the provided schema.
createTables(List<TableSchema> schemas) → Future<DbResult>
Create multiple tables schemas List of table schemas Returns DbResult to allow graceful error handling for business logic errors
delete(String tableName) → DeleteBuilder
Get a delete builder to remove records.
deleteDatabase({String? dbPath, String? dbName}) → Future<void>
Delete database dbPath Optional database path to delete dbName Optional database name to delete Removes current instance from instance pool
deleteSpace(String spaceName) → Future<DbResult>
Delete a space spaceName Space name to delete Cannot delete the default space or the currently active space Returns DbResult to allow graceful error handling for business logic errors
dropTable(String tableName) → Future<DbResult>
Drop table tableName Table name Returns DbResult to allow graceful error handling for business logic errors
flush({bool flushStorage = true}) → Future<void>
Flush pending writes to disk. flushStorage When true (default), also flush underlying storage buffers.
getSpaceInfo({bool useCache = true}) → Future<SpaceInfo>
Get information about the current space Returns detailed information about the current working space useCache Whether to use cached data. Defaults to true. Set to false to get the latest data.
getTableInfo(String tableName) → Future<TableInfo?>
Get table information including:
getTableSchema(String tableName) → Future<TableSchema?>
Get table schema tableName Table name Returns the TableSchema if found, otherwise null.
getValue(String key, {bool isGlobal = false}) → Future
Get a value from the KV store.
getVersion() → Future<int>
Get current database version number Only used for user-defined maintenance, not involved in any database internal logic.
initialize({String? dbPath, String? dbName, DataStoreConfig? config, bool reinitialize = false, bool noPersistOnClose = false, bool applyActiveSpaceOnDefault = true}) → Future<void>
Initialize database Ensure the engine is fully initialized before any operations.
insert(String tableName, Map<String, dynamic> data) → Future<DbResult>
Insert a record into a table.
listSpaces() → Future<List<String>>
List all space names (e.g. for multi-account switch or admin). Returns sorted list; at least contains 'default'.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
query(String tableName) → QueryBuilder
Get a query builder for chain-style operations.
queryMigrationTaskStatus(String taskId) → Future<MigrationStatus?>
查询迁移任务状态 taskId 任务ID，可从updateSchema()方法中直接获取 返回任务的详细状态，如果任务不存在则返回null
removeValue(String key, {bool isGlobal = false}) → Future<DbResult>
Delete key-value pair key Key isGlobal Whether it's global key-value pair, default false
restore(String backupPath, {bool deleteAfterRestore = false, bool cleanupBeforeRestore = true}) → Future<bool>
Restore database from backup backupPath Backup file path deleteAfterRestore Whether to delete the backup file after restore, default is false cleanupBeforeRestore Whether to cleanup the related data before restore, default is true
setValue(String key, dynamic value, {Duration? ttl, DateTime? expiresAt, bool isGlobal = false}) → Future<DbResult>
Set a key-value pair in the KV store.
setVersion(int version) → Future<void>
Set database version number Only used for user-defined maintenance, not involved in any database internal logic. version New version number to set
streamQuery(String tableName) → StreamQueryBuilder
Get a stream query builder for reactive data updates.
switchSpace({String spaceName = 'default', bool keepActive = true}) → Future<bool>
Switch to a different data space.
tableExists(String tableName) → Future<bool>
Check if a table has been defined in the current database (space‑agnostic).
toString() → String
A string representation of this object.
inherited
transaction<T>(FutureOr<T> action(), {bool rollbackOnError = true, bool? persistRecoveryOnCommit, TransactionIsolationLevel? isolation}) → Future<TransactionResult>
Run a transaction scope action Transaction action rollbackOnError Rolls back on error if true. persistRecoveryOnCommit Overrides the default recovery mechanism for this transaction. isolation Overrides the default isolation level for this transaction.
update(String tableName, [Map<String, dynamic> data = const {}]) → UpdateBuilder
Get an update builder to modify records.
updateSchema(String tableName) → SchemaBuilder
Update table schema, supports chain operations tableName Table name
upsert(String tableName, Map<String, dynamic> data) → Future<DbResult>
Upsert a record: updates if it exists, otherwise inserts.
vectorSearch(String tableName, {required String fieldName, required VectorData queryVector, int topK = 10, int? efSearch, double? distanceThreshold}) → Future<List<VectorSearchResult>>
Perform an approximate nearest neighbor (ANN) vector similarity search.
watchValue<T>(String key, {bool isGlobal = false, T? defaultValue, bool distinct = true}) → Stream<T?>
Watch a key-value pair for changes.
watchValues(Iterable<String> keys, {bool isGlobal = false, bool distinct = true}) → Stream<Map<String, dynamic>>
Watch multiple key-value pairs for changes.

Operators

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

Static Methods

memory({String? dbName, DataStoreConfig? config, List<TableSchema> schemas = const [], Future<void> onConfigure(ToStore db)?, Future<void> onCreate(ToStore db)?, Future<void> onOpen(ToStore db)?, bool reinitialize = false}) → Future<ToStore>
Open a pure in-memory database instance (no file IO).
open({String? dbPath, String? dbName, DataStoreConfig? config, List<TableSchema> schemas = const [], Future<void> onConfigure(ToStore db)?, Future<void> onCreate(ToStore db)?, Future<void> onOpen(ToStore db)?, bool reinitialize = false, bool noPersistOnClose = false, bool applyActiveSpaceOnDefault = true}) → Future<ToStore>
Open a database instance (Single-step initialization).