Add docs and examples.

Author: rkistner

example/basic_example.dart

@@ -0,0 +1,32 @@
+import 'package:sqlite_async/sqlite_async.dart';
+
+final migrations = SqliteMigrations()
+  ..add(SqliteMigration(1, (tx) async {
+    await tx.execute(
+        'CREATE TABLE test_data(id INTEGER PRIMARY KEY AUTOINCREMENT, data TEXT)');
+  }));
+
+void main() async {
+  final db = SqliteDatabase(path: 'test.db');
+  await migrations.migrate(db);
+
+  // Use execute() or executeBatch() for INSERT/UPDATE/DELETE statements
+  await db.executeBatch('INSERT INTO test_data(data) values(?)', [
+    ['Test1'],
+    ['Test2']
+  ]);
+
+  // Use getAll(), get() or getOptional() for SELECT statements
+  var results = await db.getAll('SELECT * FROM test_data');
+  print('Results: $results');
+
+  // Combine multiple statements into a single write transaction for:
+  // 1. Atomic persistence (all updates are either applied or rolled back).
+  // 2. Improved throughput.
+  await db.writeTransaction((tx) async {
+    await db.execute('INSERT INTO test_data(data) values(?)', ['Test3']);
+    await db.execute('INSERT INTO test_data(data) values(?)', ['Test4']);
+  });
+
+  await db.close();
+}

example/custom_functions_example.dart

@@ -0,0 +1,44 @@
+import 'dart:ffi';
+import 'dart:io';
+import 'dart:isolate';
+
+import 'package:sqlite_async/sqlite_async.dart';
+import 'package:sqlite3/open.dart' as sqlite_open;
+import 'package:sqlite3/sqlite3.dart' as sqlite;
+
+class TestOpenFactory extends DefaultSqliteOpenFactory {
+  TestOpenFactory({required super.path, super.sqliteOptions});
+
+  @override
+  sqlite.Database open(SqliteOpenOptions options) {
+    final db = super.open(options);
+
+    db.createFunction(
+      functionName: 'sleep',
+      argumentCount: const sqlite.AllowedArgumentCount(1),
+      function: (args) {
+        final millis = args[0] as int;
+        sleep(Duration(milliseconds: millis));
+        return millis;
+      },
+    );
+
+    db.createFunction(
+      functionName: 'isolate_name',
+      argumentCount: const sqlite.AllowedArgumentCount(0),
+      function: (args) {
+        return Isolate.current.debugName;
+      },
+    );
+
+    return db;
+  }
+}
+
+void main() async {
+  final db = SqliteDatabase.withFactory(TestOpenFactory(path: 'test.db'));
+  await db.get('SELECT sleep(5)');
+  print(await db.get('SELECT isolate_name()'));
+  print(await db.execute('SELECT isolate_name()'));
+  await db.close();
+}

example/linux_cli_example.dart

@@ -0,0 +1,33 @@
+import 'dart:ffi';
+
+import 'package:sqlite_async/sqlite_async.dart';
+import 'package:sqlite3/open.dart' as sqlite_open;
+import 'package:sqlite3/sqlite3.dart' as sqlite;
+
+const defaultSqlitePath = 'libsqlite3.so.0';
+
+class TestOpenFactory extends DefaultSqliteOpenFactory {
+  String sqlitePath;
+
+  TestOpenFactory(
+      {required super.path,
+      super.sqliteOptions,
+      this.sqlitePath = defaultSqlitePath});
+
+  @override
+  sqlite.Database open(SqliteOpenOptions options) {
+    sqlite_open.open.overrideFor(sqlite_open.OperatingSystem.linux, () {
+      return DynamicLibrary.open(sqlitePath);
+    });
+    final db = super.open(options);
+
+    return db;
+  }
+}
+
+void main() async {
+  final db = SqliteDatabase.withFactory(TestOpenFactory(path: 'test.db'));
+  final version = await db.get('SELECT sqlite_version() as version');
+  print("Version: ${version['version']}");
+  await db.close();
+}

example/migration_example.dart

@@ -0,0 +1,31 @@
+import 'package:sqlite_async/sqlite_async.dart';
+
+final migrations = SqliteMigrations()
+  ..add(SqliteMigration(1, (tx) async {
+    await tx.execute(
+        'CREATE TABLE test_data(id INTEGER PRIMARY KEY AUTOINCREMENT, data TEXT)');
+  }))
+  ..add(SqliteMigration(2, (tx) async {
+    await tx.execute('ALTER TABLE test_data ADD COLUMN comment TEXT');
+  },
+      // Optional: Add a down migration that will execute when users install an older application version.
+      // This is typically not required for Android or iOS where users cannot install older versions,
+      // but may be useful on other platforms or during development.
+      downMigration: SqliteDownMigration(toVersion: 1)
+        ..add('ALTER TABLE test_data DROP COLUMN comment')))
+  // Optional: Provide a function to initialize the database from scratch,
+  // avoiding the need to run through incremental migrations for new databases.
+  ..createDatabase = SqliteMigration(
+    2,
+    (tx) async {
+      await tx.execute(
+          'CREATE TABLE test_data(id INTEGER PRIMARY KEY AUTOINCREMENT, data TEXT, comment TEXT)');
+    },
+  );
+
+void main() async {
+  final db = SqliteDatabase(path: 'test.db');
+  // Make sure to run migrations before any other functions access the database.
+  await migrations.migrate(db);
+  await db.close();
+}

example/watch_example.dart

@@ -0,0 +1,44 @@
+import 'package:sqlite_async/sqlite_async.dart';
+
+final migrations = SqliteMigrations()
+  ..add(SqliteMigration(1, (tx) async {
+    await tx.execute(
+        'CREATE TABLE test_data(id INTEGER PRIMARY KEY AUTOINCREMENT, data TEXT)');
+  }));
+
+void main() async {
+  final db = SqliteDatabase(path: 'test.db');
+  await migrations.migrate(db);
+
+  // This query is re-executed every time test_data changes.
+  var stream1 = db.watch('SELECT data FROM test_data');
+  var subscription1 = stream1.listen((results) {
+    print(results);
+  });
+
+  // Use this to get notifications of changes on one or more tables.
+  var stream2 = db.onChange(['test_data']);
+  var subscription2 = stream2.listen((changes) {
+    print(changes);
+  });
+
+  // This achieves the same as db.watch(), but:
+  // 1. Explicitly specifies the tables to watch for changes.
+  // 2. May run any number of queries when a change is triggered.
+  var stream3 = db.onChange(['test_data']).asyncMap((event) async {
+    return db.getAll('SELECT count() as count FROM test_data');
+  });
+  var subscription3 = stream3.listen((results) {
+    print(results);
+  });
+
+  for (var i = 0; i < 5; i++) {
+    await db.execute('INSERT INTO test_data(data) values(?)', ['Test $i']);
+    await Future.delayed(Duration(milliseconds: 100));
+  }
+
+  subscription1.cancel();
+  subscription2.cancel();
+  subscription3.cancel();
+  await db.close();
+}

lib/sqlite_async.dart

@@ -9,3 +9,4 @@ export 'src/sqlite_database.dart';
 export 'src/sqlite_options.dart';
 export 'src/sqlite_open_factory.dart';
 export 'src/sqlite_migrations.dart';
+export 'src/isolate_connection_factory.dart';

lib/src/isolate_connection_factory.dart

@@ -9,6 +9,7 @@ import 'sqlite_connection_impl.dart';
 import 'sqlite_open_factory.dart';
 import 'update_notification.dart';
 
+/// A connection factory that can be passed to different isolates.
 class IsolateConnectionFactory {
   SqliteOpenFactory openFactory;
   SerializedMutex mutex;
@@ -19,6 +20,9 @@ class IsolateConnectionFactory {
       required this.mutex,
       required this.upstreamPort});
 
+  /// Open a new SqliteConnection.
+  ///
+  /// This opens a single connection in a background execution isolate.
   SqliteConnection open({String? debugName, bool readOnly = false}) {
     final updates = _IsolateUpdateListener(upstreamPort);
 

lib/src/log.dart

@@ -13,12 +13,10 @@ import 'sqlite_options.dart';
 import 'sqlite_queries.dart';
 import 'update_notification.dart';
 
-/// A managed database.
+/// A SQLite database instance.
 ///
-/// Use one instance per database file.
-///
-/// Use [SqliteDatabase.connect] to connect to the PowerSync service,
-/// to keep the local database in sync with the remote database.
+/// Use one instance per database file. If multiple instances are used, update
+/// notifications may not trigger, and calls may fail with "SQLITE_BUSY" errors.
 class SqliteDatabase with SqliteQueries implements SqliteConnection {
   /// Maximum number of concurrent read transactions.
   final int maxReaders;
@@ -56,22 +54,25 @@ class SqliteDatabase with SqliteQueries implements SqliteConnection {
   /// from the last committed write transaction.
   ///
   /// A maximum of [maxReaders] concurrent read transactions are allowed.
-  ///
-  /// Advanced: Use [sqliteSetup] to execute custom initialization logic in
-  /// each database isolate.
   factory SqliteDatabase(
       {required path,
       maxReaders = 5,
       options = const SqliteOptions.defaults()}) {
     final factory =
         DefaultSqliteOpenFactory(path: path, sqliteOptions: options);
-    return SqliteDatabase.withFactory(openFactory: factory);
+    return SqliteDatabase.withFactory(factory);
   }
 
   /// Advanced: Open a database with a specified factory.
   ///
-  /// Use when control is required over the opening process.
-  SqliteDatabase.withFactory({required this.openFactory, this.maxReaders = 5}) {
+  /// The factory is used to open each database connection in background isolates.
+  ///
+  /// Use when control is required over the opening process. Examples include:
+  ///  1. Specifying the path to `libsqlite.so` on Linux.
+  ///  2. Running additional per-connection PRAGMA statements on each connection.
+  ///  3. Creating custom SQLite functions.
+  ///  4. Creating temporary views or triggers.
+  SqliteDatabase.withFactory(this.openFactory, {this.maxReaders = 5}) {
     updates = _updatesController.stream;
 
     _listenForEvents();
@@ -137,6 +138,9 @@ class SqliteDatabase with SqliteQueries implements SqliteConnection {
     });
   }
 
+  /// A connection factory that can be passed to different isolates.
+  ///
+  /// Use this to access the database in background isolates.s
   IsolateConnectionFactory isolateConnectionFactory() {
     return IsolateConnectionFactory(
         openFactory: openFactory,

lib/src/sqlite_database.dart

@@ -5,9 +5,22 @@ import 'package:sqlite3/sqlite3.dart';
 
 import 'sqlite_connection.dart';
 
+/// Migrations to initialize and update a database.
 class SqliteMigrations {
+  /// Name of table used to store migrations.
+  ///
+  /// Defaults to "_migrations".
   String migrationTable;
+
+  /// List of migrations to execute, in order. Use [add] to add new migrations.
   List<SqliteMigration> migrations = [];
+
+  /// Optional: Migration to create database from scratch.
+  ///
+  /// Use this to speed up initialization for a fresh database.
+  ///
+  /// This must be supplied _in addition to_ migrations for the same version,
+  /// and should produce the same state for the database.
   SqliteMigration? createDatabase;
 
   SqliteMigrations({this.migrationTable = "_migrations"});
@@ -34,10 +47,12 @@ class SqliteMigrations {
     migrations.add(migration);
   }
 
+  /// The current version as specified by the migrations.
   get version {
     return migrations.isEmpty ? 0 : migrations.last.toVersion;
   }
 
+  /// Get the last applied migration version in the database.
   Future<int> getCurrentVersion(SqliteWriteContext db) async {
     try {
       final currentVersionRow = await db.getOptional(
@@ -69,6 +84,9 @@ class SqliteMigrations {
     }
   }
 
+  /// Initialize or update the database.
+  ///
+  /// Throws MigrationError if the database cannot be migrated.
   Future<void> migrate(SqliteConnection db) async {
     _validateCreateDatabase();
 
@@ -167,12 +185,22 @@ class MigrationError extends Error {
 typedef SqliteMigrationFunction = FutureOr<void> Function(
     SqliteWriteContext tx);
 
+/// A migration for a single database version.
 class SqliteMigration {
+  /// Function to execute for the migration.
   final SqliteMigrationFunction fn;
+
+  /// Database version that this migration upgrades to.
   final int toVersion;
 
   /// Optional: Add a down migration to allow this migration to be reverted
   /// if the user installs an older version.
+  ///
+  /// If the user will never downgrade the application/database version, this is
+  /// not required.
+  ///
+  /// Limited downgrade support can be added by only providing downMigrations
+  /// for the last migration(s).
   SqliteDownMigration? downMigration;
 
   SqliteMigration(this.toVersion, this.fn, {this.downMigration});
@@ -189,12 +217,18 @@ class _SqliteMigrationStatement {
   }
 }
 
+/// Set of down migration statements, persisted in the database.
+///
+/// Since this will execute in an older application version, only static
+/// SQL statements are supported.
 class SqliteDownMigration {
+  /// The database version after this downgrade.
   final int toVersion;
   final List<_SqliteMigrationStatement> _statements = [];
 
   SqliteDownMigration({required this.toVersion});
 
+  /// Add an statement to execute to downgrade the database version.
   add(String sql, [List<Object?>? params]) {
     _statements.add(_SqliteMigrationStatement(sql, params ?? []));
   }