Skip to content

Latest commit

 

History

History
290 lines (215 loc) · 8.43 KB

flutter.md

File metadata and controls

290 lines (215 loc) · 8.43 KB

Flutter / Dart Integration

This guide shows how to use SQLiteAI extensions in Flutter and Dart applications.

Requirements: Dart 3.10+ / Flutter 3.38+

Available Packages

Package Description pub.dev
sqlite_vector Vector similarity search with SIMD-optimized distance functions pub.dev
sqlite_js Execute JavaScript directly in SQLite using QuickJS pub.dev
sqlite_sync Real-time sync with SQLite Cloud pub.dev
sqlite_ai On-device LLM inference with llama.cpp pub.dev
sqlite_agent Execute AI agents with MCP capabilities pub.dev
sqlite_mcp Call MCP resources from databases pub.dev

Installation

Install the packages you need:

# Flutter projects
flutter pub add sqlite_vector
flutter pub add sqlite_js
flutter pub add sqlite_sync
flutter pub add sqlite_ai
flutter pub add sqlite_agent
flutter pub add sqlite_mcp

# Dart projects
dart pub add sqlite_vector
dart pub add sqlite_js
dart pub add sqlite_sync
dart pub add sqlite_ai
dart pub add sqlite_agent
dart pub add sqlite_mcp

Or add to pubspec.yaml:

dependencies:
  sqlite3: ^3.0.0
  # Add the packages you need
  sqlite_vector: ^0.9.85
  sqlite_js: ^1.2.3
  sqlite_sync: ^0.8.64
  sqlite_ai: ^0.7.59
  sqlite_agent: ^0.1.6
  sqlite_mcp: ^0.1.5

Each package uses Dart build hooks to automatically bundle the correct native library for each platform. No additional configuration is needed.

Supported Platforms

Platform Architectures
Android arm64, arm, x64
iOS arm64 (device + simulator)
macOS arm64, x64
Linux arm64, x64
Windows x64

Usage

With sqlite3

import 'package:sqlite3/sqlite3.dart';
import 'package:sqlite_vector/sqlite_vector.dart';
import 'package:sqlite_js/sqlite_js.dart';
import 'package:sqlite_sync/sqlite_sync.dart';
import 'package:sqlite_ai/sqlite_ai.dart';
import 'package:sqlite_agent/sqlite_agent.dart';
import 'package:sqlite_mcp/sqlite_mcp.dart';

void main() {
  // Load extensions once at app startup
  sqlite3.loadSqliteVectorExtension();
  sqlite3.loadSqliteJsExtension();
  sqlite3.loadSqliteSyncExtension();
  sqlite3.loadSqliteAiExtension();
  sqlite3.loadSqliteAgentExtension();
  sqlite3.loadSqliteMcpExtension();

  final db = sqlite3.openInMemory();

  // Now all extension functions are available
  print(db.select('SELECT vector_version()').first.values.first);
  print(db.select('SELECT js_version()').first.values.first);
  print(db.select('SELECT cloudsync_version()').first.values.first);
  print(db.select('SELECT ai_version()').first.values.first);
  print(db.select('SELECT agent_version()').first.values.first);
  print(db.select('SELECT mcp_version()').first.values.first);

  db.dispose();
}

With drift

drift is a popular ORM built on top of sqlite3. The extensions integrate seamlessly:

import 'dart:io';
import 'package:sqlite3/sqlite3.dart';
import 'package:sqlite_vector/sqlite_vector.dart';
import 'package:sqlite_js/sqlite_js.dart';
import 'package:sqlite_sync/sqlite_sync.dart';
import 'package:drift/native.dart';

Sqlite3 loadExtensions() {
  sqlite3.loadSqliteVectorExtension();
  sqlite3.loadSqliteJsExtension();
  sqlite3.loadSqliteSyncExtension();
  // Add other extensions as needed
  return sqlite3;
}

// Use when creating your database connection
LazyDatabase openConnection() {
  return LazyDatabase(() async {
    final file = File('path/to/db.sqlite');
    return NativeDatabase.createInBackground(
      file,
      sqlite3: loadExtensions,
    );
  });
}

Extension Examples

sqlite-vector: Vector Similarity Search

// Create a table with a BLOB column for vectors
db.execute('CREATE TABLE items (id INTEGER PRIMARY KEY, embedding BLOB)');

// Insert vectors
final stmt = db.prepare('INSERT INTO items (embedding) VALUES (vector_as_f32(?))');
stmt.execute(['[1.0, 2.0, 3.0, 4.0]']);
stmt.execute(['[5.0, 6.0, 7.0, 8.0]']);
stmt.dispose();

// Initialize the vector index
db.execute("SELECT vector_init('items', 'embedding', 'type=FLOAT32,dimension=4')");

// Find nearest neighbors
final results = db.select('''
  SELECT e.id, v.distance FROM items AS e
  JOIN vector_full_scan('items', 'embedding', vector_as_f32('[1.0, 2.0, 3.0, 4.0]'), 2) AS v
  ON e.id = v.rowid
''');

for (final row in results) {
  print('id=${row['id']}, distance=${row['distance']}');
}

sqlite-js: JavaScript Evaluation

// Evaluate JavaScript expressions
final result = db.select("SELECT js_eval('1 + 2 + 3')").first.values.first;
print('Result: $result'); // Result: 6

// Use JavaScript for complex calculations
final json = db.select("SELECT js_eval('JSON.stringify({a: 1, b: 2})')").first.values.first;
print('JSON: $json'); // JSON: {"a":1,"b":2}

sqlite-sync: UUID Generation

// Generate UUIDs (UUIDv7) - works without initialization
final uuid1 = db.select('SELECT cloudsync_uuid()').first.values.first;
final uuid2 = db.select('SELECT cloudsync_uuid()').first.values.first;
print('UUID 1: $uuid1');
print('UUID 2: $uuid2');

// For cloud sync features, initialize with your SQLite Cloud connection
// db.execute("SELECT cloudsync_init('sqlitecloud://...')");

sqlite-ai, sqlite-agent, sqlite-mcp

These extensions require additional setup (GGUF models, MCP server connections). See the API documentation for each extension:

How It Works

All SQLiteAI packages use Dart's native assets system (build hooks) introduced in Dart 3.10 / Flutter 3.38. This is the same mechanism used by the sqlite3 package itself.

Key points:

  • No Gradle, CocoaPods, or CMake configuration needed — the build hook handles everything
  • Pre-built binaries are bundled in the package and selected at build time based on target platform/architecture
  • The @Native FFI annotation resolves the extension's init function from the bundled native library
  • loadSqlite*Extension() calls ensureExtensionLoaded() which registers the extension with SQLite

API References

Extension API Documentation
sqlite-vector API.md
sqlite-js API.md
sqlite-sync API.md
sqlite-ai API.md
sqlite-agent API.md
sqlite-mcp API.md

Example Project

A complete Flutter example app demonstrating all extensions is available at: examples/flutter

cd examples/flutter

# Generate platform scaffolding (only needed once)
flutter create . --project-name sqliteai_flutter_example

# Install dependencies and run
flutter pub get
flutter run

Or run as a Dart CLI (no UI):

dart pub get
dart run lib/main.dart

Troubleshooting

"Pre-built binary not found"

This error occurs when running on a platform/architecture that doesn't have a bundled binary. The packages support the platforms listed above.

Extension loads but functions don't work

Make sure you've loaded the extension before opening the database or using its functions:

// Correct order
sqlite3.loadSqliteVectorExtension(); // Load first
final db = sqlite3.openInMemory();    // Then open database

"Dart SDK version too old"

Build hooks require Dart 3.10+ / Flutter 3.38+. Update your SDK:

flutter upgrade

Extension-specific errors

Some extensions require initialization before certain functions work:

  • sqlite-sync: cloudsync_uuid() works immediately, but sync features need cloudsync_init()
  • sqlite-ai: Requires a GGUF model file for inference
  • sqlite-mcp: Requires MCP server connection configuration
  • sqlite-agent: Requires both sqlite-ai and sqlite-mcp setup