stoolap_flutter 2.0.0

High-performance, pure Rust embedded SQL database for Flutter with native Vector Search, MVCC transactions, and reactive Streams.

Stoolap Flutter SDK

The high-performance SQL database that ships with your app.

What's New in 2.0.0 🚀

• Prepared Statements: Parse once, execute many times with zero parse overhead.
• Named Parameters: Use :name syntax for readable, maintainable queries.
• Query Timeouts: Cancel queries that exceed time limits.
• Snapshot Isolation: Full MVCC transaction isolation levels.
• Semantic Search: Built-in EMBED() function for AI-powered search — no external APIs.
• Semantic Cache: Query result caching with stats and control.
• Performance: Fixed redundant FFI matching and wrapped batch execution in transactions.
• Full API Parity: 100% coverage of the Stoolap Rust API v0.4.0.

---

What is Stoolap?

Stoolap is a modern embedded SQL database that provides full ACID transactions with MVCC, a sophisticated cost-based query optimizer, and features that rival established databases like PostgreSQL and DuckDB. Built entirely in Rust with minimal unsafe code (only for FFI and performance-critical hot paths), Stoolap features multiple index types (B-tree, Hash, Bitmap, HNSW), native vector search with semantic search support, parallel query execution, and comprehensive SQL support including window functions, CTEs, and temporal queries.

Official Reference: https://stoolap.io/ Pub.dev: https://pub.dev/packages/stoolap_flutter

---

Features 📦

• 🦀 Pure Rust Core: Memory-safe and lightning-fast database engine.
• 🔍 Native Vector Search: VECTOR type and HNSW indexes for sub-linear semantic search.
• 🧠 Built-in Semantic Search: EMBED() function converts text to vectors inside Rust — no external APIs needed.
• ⚡ Parallel Execution: Automatically parallelizes joins, sorts, and aggregations across all CPU cores.
• 🛡️ MVCC Transactions: Full ACID compliance with snapshot isolation. Readers never block writers.
• 🕰️ Time-Travel Queries: Query your data exactly as it existed in the past using the AS OF syntax.
• 🔄 Reactive API: Built-in support for "Live Queries" using Dart Streams.
• 🏗️ Advanced SQL: Supports CTEs (including Recursive), Window Functions, and standard SQL joins.
• 📱 Mobile Optimized: Optimized with SIMD for ARM64 (M1/M2 and modern Android chips).
• 📋 Prepared Statements: Parse SQL once, execute many times with zero parse overhead.
• 🏷️ Named Parameters: Use :name syntax for readable, maintainable queries.
• ⏱️ Query Timeouts: Cancel queries that exceed time limits.
• 🔒 Isolation Levels: Choose between Read Committed and Snapshot isolation.

---

Quick Start 🚀

1. Installation

Add stoolap_flutter to your pubspec.yaml:

dependencies:
  stoolap_flutter: ^2.0.0

2. Initialization

import 'package:stoolap_flutter/stoolap_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await StoolapDatabase.init();
  runApp(const MyApp());
}

3. Basic Usage

final db = StoolapDatabase();
await db.open('my_app_data.db');

// Execute DDL
await db.execute('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)');

// Insert with positional parameters
await db.execute('INSERT INTO users (name, email) VALUES (?, ?)', params: ['Alice', '[e-mail]']);

// Insert with named parameters
await db.executeNamed(
  'INSERT INTO users (name, email) VALUES (:name, :email)',
  namedParams: {'name': 'Bob', 'email': '[e-mail]'},
);

// Query
final rows = await db.query('SELECT * FROM users');
for (var row in rows) {
  print('User: ${row.values[1]}');
}

---

Advanced Features 🛠️

Prepared Statements

Parse SQL once and execute many times with zero parse overhead:

final stmt = await db.prepare('INSERT INTO logs (level, message) VALUES (?, ?)');

// Execute many times — no parsing, no cache lookup
for (var entry in logEntries) {
  await stmt.execute(params: [entry.level, entry.message]);
}

Named Parameters

Use readable :name placeholders:

await db.executeNamed(
  'INSERT INTO users (name, email, age) VALUES (:name, :email, :age)',
  namedParams: {'name': 'Charlie', 'email': '[e-mail]', 'age': 25},
);

Query Timeouts

Cancel queries that exceed time limits:

final results = await db.queryWithTimeout(
  'SELECT * FROM large_table WHERE complex_condition',
  timeout: Duration(seconds: 5),
);

Snapshot Isolation

Choose between isolation levels:

// Read Committed (default) — each statement sees committed data
await db.begin();

// Snapshot — entire transaction sees consistent snapshot from BEGIN
await db.begin(isolation: 'snapshot');
await db.execute('SELECT * FROM accounts'); // Sees data as of BEGIN
await db.commit();

Semantic Vector Search

Stoolap handles embeddings natively with built-in EMBED():

// Create table with vector support
await db.execute('''
  CREATE TABLE items (
    id INTEGER PRIMARY KEY,
    description TEXT,
    embedding VECTOR(384)
  )
''');

// Insert with auto-generated embedding
await db.execute(
  "INSERT INTO items (description, embedding) VALUES (?, EMBED(?))",
  params: ['high-performance database', 'high-performance database'],
);

// Semantic search using the convenience method
final results = await db.semanticSearch(
  table: 'items',
  embeddingColumn: 'embedding',
  query: 'fast SQL engine',
  limit: 5,
);

Reactive Live Queries

StreamBuilder<List<StoolapRow>>(
  stream: db.watch('SELECT * FROM users ORDER BY id DESC'),
  builder: (context, snapshot) {
    if (!snapshot.hasData) return const CircularProgressIndicator();
    final users = snapshot.data!;
    return ListView.builder(
      itemCount: users.length,
      itemBuilder: (context, index) => ListTile(
        title: Text(users[index].values[1].toString()),
      ),
    );
  },
);

Table Utilities

// Check if a table exists
if (await db.tableExists('users')) {
  // Table exists
}

// Create a point-in-time snapshot
await db.createSnapshot();

// Get engine version
final version = await StoolapDatabase.version();

// Semantic cache stats
final stats = await db.semanticCacheStats();
await db.clearSemanticCache();

---

Performance & Benchmarks ⚡

Stoolap is engineered for high-performance mobile and edge workloads. Unlike single-threaded databases, it leverages Rayon for automatic query parallelization and SIMD (NEON/AVX) for lightning-fast vector math.

Real-World Performance (vs SQLite & DuckDB)

Official benchmarks performed on Apple M1 Pro (16GB RAM, macOS 15) using identical 10k row workloads with Stoolap v0.4.0, SQLite 3.45.0, and DuckDB 0.10.0. Source: Stoolap Official Benchmarks.

Operation	Stoolap	SQLite	DuckDB	Speedup (vs SQLite)
COUNT DISTINCT	0.37 µs	105.98 µs	219.91 µs	286x
Subquery Compare	5.52 µs	1424.07 µs	293.51 µs	258x
Aggregation (GROUP BY)	48.81 µs	1403.39 µs	104.32 µs	29x
SELECT by ID	0.12 µs	0.21 µs	145.55 µs	1.7x
Vector Search (k-NN)	4ms	N/A	N/A	Native

Mobile Performance Comparison

Feature	Stoolap (Rust)	SQLite (C)	Hive (Dart)	Isar (Dart)
Parallelism	Automatic (Multi-core)	Single-threaded	Single-threaded	Single-threaded
Concurrency	MVCC (Readers don't block)	Lock-based	Lock-based	Lock-based
Vector Index	Native HNSW	✗	✗	✗
Optimizer	Cost-Based (PostgreSQL-style)	Rule-Based	✗	✗
Prepared Statements	Parse-once, execute-many	✓	✗	✓
Named Parameters	:name syntax	✗	✗	✗
Reactive Queries	Built-in Streams	✗	✓	✓
Semantic Search	Built-in EMBED()	✗	✗	✗

Why is Stoolap faster?

1. Pure Rust Performance: Compiled with LTO and opt-level = 3 for mobile ARM64.
2. Snapshot Isolation (MVCC): High-throughput concurrent reads and writes without contention.
3. Adaptive Query Execution: The optimizer learns from actual data distributions to choose the fastest plan.
4. Hardware Acceleration: Direct use of ARM NEON instructions for vector distance metrics.
5. Batch Transaction Wrapping: Multiple statements execute in a single transaction for minimal overhead.
6. Prepared Statement Caching: Parse SQL once, execute plan with zero parse-lookup cost.

---

Connection String Options

Configure your database with Stoolap connection strings:

// File-based with options
await db.open('file:///data/app.db?sync=full&checkpoint_interval=60');

// In-memory (unique instance)
await db.open(':memory:');

// Named in-memory (shared engine)
await db.open('memory://mydb');

Parameter	Default	Description
sync	normal	Sync mode: none, normal, full
checkpoint_interval	60	Seconds between checkpoint cycles
wal_compression	on	LZ4 compression for WAL entries
compression	–	Sets both wal_compression and volume_compression
target_volume_rows	1048576	Target rows per cold volume

---

Documentation 📚

• 🦀 Rust Engine Docs – Full SQL reference and architecture details.
• 🎯 Vector Search Guide – Learn how to build semantic search.
• 🧠 Semantic Search Guide – Built-in EMBED() function.
• 🤝 Contributing – Help us build the future of mobile databases.

---

Join our community 🤝

We're building the most powerful embedded database for Flutter. Join us on GitHub to report issues, suggest features, or contribute code.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.