FFastDB π v1.0.1
A fast, crash-safe, pure-Dart NoSQL database for Flutter & server-side Dart.
Features
| Feature | FastDB | Hive | Isar |
|---|---|---|---|
| Pure Dart | β | β | β (native) |
| No code generation | β | β | β |
| B-Tree primary index | β | β | β |
| Secondary indexes | β | β | β |
| Write-Ahead Log (WAL) | β | β | β |
| Crash recovery | β | β | β |
| File locking | β | β | β |
| Fluent QueryBuilder | β | β | β |
| Reactive watchers | β | β | β |
| Transactions | β | β | β |
DateTime support |
β | β | β |
| Web support | β | β | β |
| WASM support | β | β | β |
Also built in: full-text search, composite indexes, authenticated encryption, JSON export/import, schema migrations and a compact binary document format.
Getting Started
dependencies:
ffastdb: ^1.0.1
Open a database (Flutter β mobile, desktop, web, WASM)
import 'package:flutter/foundation.dart' show kIsWeb;
import 'package:flutter/material.dart';
import 'package:ffastdb/ffastdb.dart';
import 'package:path_provider/path_provider.dart'; // add to YOUR app's pubspec
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
// Native: a persistent directory. Web: ignored (data lives in IndexedDB).
final dir = kIsWeb ? '' : (await getApplicationDocumentsDirectory()).path;
final db = await openDatabase(
'myapp',
directory: dir,
indexes: ['status'], // HashIndex: O(1) equals
sortedIndexes: ['createdAt', 'age'], // SortedIndex: ranges, sorting
ftsIndexes: ['description'], // full-text search
compositeIndexes: [['status', 'createdAt']], // multi-field AND
encryptionKey: 'your_secret_key', // optional
);
runApp(MyApp(db: db));
}
openDatabase()returns the open database when called again for the same database (e.g. from several places at startup) and replaces it when you ask for a different one.path_provideris not a dependency offfastdb.- One process (isolate) owns a database file at a time; a second opener gets a clear "locked" error.
Persist indexes when the app goes to the background
class _AppState extends State<MyApp> with WidgetsBindingObserver {
@override
void didChangeAppLifecycleState(AppLifecycleState state) {
if (state == AppLifecycleState.paused) widget.db.flush();
}
// ... addObserver / removeObserver in initState / dispose
}
flush() makes every write durable and saves the secondary indexes. If the OS
then kills the app, the next start loads the indexes instead of rebuilding them
from every document.
Server-side Dart / manual setup
import 'package:ffastdb/ffastdb.dart';
// File on disk + WAL + file lock
final db = await FfastDb.init(
WalStorageStrategy(
main: IoStorageStrategy('/data/myapp/users.fdb'),
wal: IoStorageStrategy('/data/myapp/users.fdb.wal'),
durability: Durability.full,
),
indexes: ['status'],
);
final same = FfastDb.instance; // the singleton, anywhere in your app
await FfastDb.disposeInstance(); // at shutdown
// Tests / in-memory (no persistence)
final mem = FastDB(MemoryStorageStrategy());
await mem.open();
Durability
| Mode | Each write | Survives app crash / OS killing the app | Survives power loss / OS crash |
|---|---|---|---|
Durability.normal (default for openDatabase) |
no fsync | β | may lose the latest writes β never corrupts |
Durability.full |
fsynced before await returns |
β | β |
final db = await openDatabase('bank', directory: dir, durability: Durability.full);
normal works like SQLite's synchronous=NORMAL: the main file is only
written after the WAL is fsynced, so a power loss can roll back to an earlier
state but never leaves a half-applied one. db.flush() and db.close() make
everything durable in both modes. Single writes are ~4-7x faster in normal.
On the web every write is committed to IndexedDB; the option is ignored.
Encryption
// Password (stretched with PBKDF2-HMAC-SHA256, 100k iterations by default):
final db = await openDatabase('secure', directory: dir, encryptionKey: 'passphrase');
// Strongest: a random 32-byte key kept in the platform's secure storage
final secure = FastDB(EncryptedStorageStrategy.withRawKey(storage, key32Bytes));
- AES-256 with a fresh nonce every time a 1 KB sector is rewritten, plus an HMAC-SHA256 tag per sector: tampered or corrupted data fails on read.
- A wrong key is rejected by
open(). - Opening costs ~0.2 s with a password (PBKDF2); a raw key opens instantly.
Tune with
EncryptedStorageStrategy(base, password, pbkdf2Iterations: ...). - Files encrypted by ffastdb β€ 0.3.5 keep working in their legacy format
(
isLegacyFormat). To upgrade one,exportJson()it andimportJson()into a new database.
Documents
Insert, update, delete
final id = await db.insert({
'name': 'Alice',
'age': 30,
'city': 'London',
'createdAt': DateTime.now(),
});
await db.put(42, {'name': 'Bob'}); // manual id
await db.upsert(42, {'age': 26}); // update or insert by id
await db.upsertWhere('email', 'a@b.c', {'name': 'Ann'}); // by unique field
final ids = await db.insertAll([ // bulk: much faster
{'name': 'Clara', 'city': 'Tokyo', 'age': 28},
{'name': 'Dana', 'city': 'London', 'age': 35},
]);
await db.update(id, {'age': 31}); // merges fields
await db.delete(id);
// Atomic bulk operations (all or nothing)
await db.updateWhere((q) => q.where('city').equals('London').findIds(), {'country': 'UK'});
await db.deleteWhere((q) => q.where('active').equals(false).findIds());
Read
final doc = await db.findById(id); // O(log n)
final docs = await db.findByIds(ids); // one batched read, keeps order
final all = await db.getAll();
final n = await db.count(); // O(1)
final has = await db.exists(id);
// Lazy: one document at a time
await for (final d in db.findStream((q) => q.where('city').equals('London').findIds())) {
print(d);
}
Supported data types
int (64-bit), double (incl. NaN/Β±Infinity), String, bool, null,
DateTime (UTC microseconds, read back with isUtc: true), Uint8List,
nested List / Map, and Firebase types by duck-typing (Timestamp β
DateTime, GeoPoint β {latitude, longitude}, DocumentReference β path,
Blob β Uint8List). Other objects are stored via toJson() (as a document)
or toString() (nested). See SUPPORTED_DATA_TYPES.md.
Documents are stored in a compact binary format. Databases written by older versions (JSON format) are read without any migration step.
Export / import JSON
final json = await db.exportJson(); // JSON array, ascending id order
final ids = await other.importJson(json); // inserted as new documents
Export maps values onto plain JSON (DateTime β ISO-8601 UTC, Uint8List β
base64, NaN/Β±Infinity β null) and keeps each document's ffdbID; import drops
ffdbID (the database assigns ids) and keeps plain JSON types.
Queries
All query methods return Futures.
// Exact match β O(1) with a HashIndex
final ids = await db.query().where('city').equals('London').findIds();
// Ranges β O(log n) with a SortedIndex
await db.query().where('age').between(18, 65).findIds();
await db.query().where('age').greaterThan(60).findIds();
await db.query().where('age').lessThanOrEqualTo(25).findIds();
// AND (most selective index first), OR, NOT, isIn, null checks
await db.query().where('city').equals('London').where('age').between(25, 40).findIds();
await db.query().where('city').equals('London').or().where('city').equals('Paris').findIds();
await db.query().where('city').not().equals('London').findIds();
await db.query().where('city').isIn(['London', 'Tokyo']).findIds();
await db.query().where('email').isNull().findIds();
// Strings (case-sensitive) and full-text search (case-insensitive tokens)
await db.query().where('name').startsWith('Al').findIds();
await db.query().where('name').contains('ice').findIds();
await db.query().where('description').fts('payment failed').find();
// Sorting + pagination (sortBy needs a SortedIndex)
await db.query().where('city').equals('London').sortBy('age', descending: true).skip(20).limit(10).findIds();
// Documents instead of ids
final docs = await db.query().where('city').equals('London').find();
final first = await db.query().where('name').startsWith('Al').findFirst();
final count = await db.query().where('city').equals('London').count(); // O(1) for one equals
// Aggregations
await db.sumWhere((q) => q.where('active').equals(true).findIds(), 'age');
await db.avgWhere((q) => q.where('active').equals(true).findIds(), 'age');
await db.maxWhere((q) => q.where('city').equals('London').findIds(), 'age');
// Why is a query slow? Print the plan.
print(db.query().where('city').equals('London').where('age').between(18, 65).explain());
Conditions on fields without an index still work (in-memory filter); inside an AND they only scan the candidates left by the indexed conditions.
Indexes
Declare them in openDatabase() / FfastDb.init(), or register them before
open():
final db = FastDB(storage);
db.addIndex('city'); // HashIndex β equals
db.addSortedIndex('age'); // SortedIndex β ranges, sortBy, startsWith
db.addBitmaskIndex('active'); // booleans / small enums
db.addCompositeIndex(['city', 'status']); // multi-field AND
db.addFtsIndex('description'); // full-text search
await db.open();
An index added after open() needs await db.reindex(field: 'city')
(await db.reindex() rebuilds all). Indexes are persisted, so there is no
reason to reindex on every start.
Transactions
await db.transaction(() async {
final id = await db.insert({'name': 'Alice', 'balance': 100});
await db.update(id, {'balance': 80});
if (somethingWrong) throw Exception('abort'); // everything above is undone
});
- Atomic: all or nothing (fully crash-safe with a
WalStorageStrategy, the default on native). - Isolated: other callers' reads and writes wait until it finishes; calls made
inside it β including nested
transaction()calls β join it.
Reactive watchers
db.watch('status').listen((ids) => print('status index: $ids'));
db.watchDocs('status').listen((docs) => print(docs));
db.query().where('status').equals('pending').watch().listen((docs) => print(docs));
A burst of writes produces one emission with the final state.
TypeAdapters (typed objects)
class User {
final String name;
final int age;
User(this.name, this.age);
}
class UserAdapter extends TypeAdapter<User> {
@override
int get typeId => 1; // unique, never change it once data exists (256 and 512 are reserved)
@override
User read(BinaryReader reader) {
final n = reader.readUint8();
final f = {for (int i = 0; i < n; i++) reader.readUint8(): reader.readDynamic()};
return User(f[0] as String, f[1] as int? ?? 0); // tolerate missing slots
}
@override
void write(BinaryWriter writer, User user) {
writer.writeUint8(2); // number of slots
writer.writeUint8(0); writer.writeDynamic(user.name);
writer.writeUint8(1); writer.writeDynamic(user.age);
}
}
db.registerAdapter(UserAdapter()); // before inserting/reading Users
final id = await db.insert(User('Alice', 30));
final user = await db.findById(id) as User;
Numbered slots keep old data readable when you add fields: add new slot numbers, never reuse old ones.
Schema migrations
final db = await openDatabase(
'myapp',
directory: dir,
version: 2,
migrations: {
1: (doc) => {...doc as Map<String, dynamic>, 'country': 'unknown'}, // v1 β v2
},
);
Migrations run once, atomically, when the stored version is lower.
Compaction
Updates and deletes leave dead space behind; compact() reclaims it (atomic
with the WAL):
await db.compact();
final db = FastDB(storage, autoCompactThreshold: 0.3); // auto when >30% dead (off by default)
Performance
Measured on a Windows desktop (Dart VM). Run them yourself with
dart run benchmark/<name>.dart.
In-memory storage, 1M documents (benchmark/million_benchmark.dart):
| Operation | Throughput |
|---|---|
Batch insert (insertAll) |
~200k docs/s |
Sequential insert |
~180k ops/s |
findById |
~520k ops/s |
| HashIndex query | ~1.1M ops/s |
| SortedIndex range query | ~660k ops/s |
On disk with the WAL (20k documents, openDatabase defaults):
| Operation | Throughput |
|---|---|
insertAll |
~59k docs/s |
insert β Durability.normal / Durability.full |
~4.5k / ~650 ops/s |
update β normal / full |
~2.2k / ~600 ops/s |
findById |
~15k ops/s |
getAll |
~170k docs/s |
Flutter comparison (flutter_benchmark/, real disk, 10k docs β measured
with ffastdb 0.3.5, before the optimizations in the current version):
| Operation | ffastdb |
isar_community |
sembast |
|---|---|---|---|
insertAll (bulk) |
39.7k ops/s | 153.8k ops/s | 15.3k ops/s |
| single insert (fsync per write) | 382 ops/s | 498 ops/s | 97 ops/s |
| indexed query (2k queries) | 151 ops/s | 583 ops/s | 245 ops/s |
findById (5k lookups) |
13.9k ops/s | 9.2k ops/s | 333.3k ops/s |
cd flutter_benchmark && dart run bin/run_benchmark.dart 10000
Architecture
FastDB
βββ B-Tree primary index (O(log n), bulk-load O(n))
βββ Secondary indexes: Hash Β· Sorted Β· Bitmask Β· Composite Β· Full-text
βββ Binary document codec (CRC32 per document)
βββ LRU page cache
βββ WAL (WalStorageStrategy)
β βββ per-transaction COMMIT markers, CRC32 per entry
β βββ Durability.full / Durability.normal
β βββ automatic crash recovery on open()
βββ StorageStrategy
βββ IoStorageStrategy (mobile / desktop / server β file lock)
βββ IndexedDbStorageStrategy (web β default)
βββ LocalStorageStrategy (web β localStorage)
βββ MemoryStorageStrategy (tests)
βββ EncryptedStorageStrategy (wrapper β AES-256 + HMAC-SHA256)
βββ BufferedStorageStrategy (wrapper β write coalescing)
Files on disk
For openDatabase('users', directory: '/data'):
/data/users.fdb β main database file
/data/users.fdb.wal β write-ahead log (emptied at checkpoints)
/data/users.fdb.lock β process lock (removed on close)
Support & Funding β€οΈ
If you find ffastdb valuable and want to support its continuous development, maintenance, and optimizations, you can sponsor or buy me a coffee via PayPal:
π paypal.me/gonojuarez
License
MIT Β© 2026 Gonzalo Juarez