Add readme for examples.

Author: rkistner

example/README.md

@@ -0,0 +1,9 @@
+# Examples
+
+ * [Basic setup](./basic_example.dart)
+ * [Watching queries](./watch_example.dart)
+ * [Database migrations](./migration_example.dart)
+ * [Data objects and JSON data](./json_example.dart)
+ * [Specify library path for CLI on Linux](./linux_cli_example.dart)
+ * [Create custom SQLite functions](./custom_functions_example.dart)
+ 

example/basic_example.dart

@@ -1,13 +1,18 @@
 import 'package:sqlite_async/sqlite_async.dart';
 
+/// Migrations to setup the database.
+///
+/// For more options, see `migration_example.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 {
+  // Open the database
   final db = SqliteDatabase(path: 'test.db');
+  // Run migrations - do this before any other queries
   await migrations.migrate(db);
 
   // Use execute() or executeBatch() for INSERT/UPDATE/DELETE statements
@@ -28,5 +33,6 @@ void main() async {
     await db.execute('INSERT INTO test_data(data) values(?)', ['Test4']);
   });
 
+  // Close database to release resources
   await db.close();
 }

example/custom_functions_example.dart

@@ -6,6 +6,8 @@ import 'package:sqlite_async/sqlite_async.dart';
 import 'package:sqlite3/open.dart' as sqlite_open;
 import 'package:sqlite3/sqlite3.dart' as sqlite;
 
+/// Since the functions need to be created on every SQLite connection,
+/// we do this in a SqliteOpenFactory.
 class TestOpenFactory extends DefaultSqliteOpenFactory {
   TestOpenFactory({required super.path, super.sqliteOptions});
 

example/json_example.dart

@@ -11,12 +11,12 @@ class User {
 
   User({this.id, required this.name, required this.email});
 
-  /// For mapping query results
+  /// For mapping query results.
   factory User.fromMap(Map<String, dynamic> data) {
     return User(id: data['id'], name: data['name'], email: data['email']);
   }
 
-  /// Used for query parameters
+  /// JSON representation, used for query parameters.
   Map<String, dynamic> toJson() {
     return {'id': id, 'name': name, 'email': email};
   }
@@ -27,6 +27,14 @@ class User {
   }
 
   /// Helper to use in queries.
+  /// This produces an equivalent to:
+  ///
+  /// ```sql
+  /// SELECT
+  ///       json_each.value ->> 'id' as id,
+  ///       json_each.value ->> 'name' as name,
+  ///       json_each.value ->> 'email' as email
+  /// FROM json_each(?)
   static final selectJsonData = selectJsonColumns(['id', 'name', 'email']);
 }
 
@@ -45,20 +53,22 @@ void main() async {
     User(name: 'Alice', email: 'alice@example.org')
   ];
 
-  // Insert data and get resulting ids
+  // Insert data and get resulting ids.
+  // Here, the list of users is automatically encoded as JSON using [User.toJson].
+  // "RETURNING id" is used to get the auto-generated ids.
   var idRows = await db.execute('''
 INSERT INTO users(name, email)
 SELECT name, email FROM (${User.selectJsonData('?')})
 RETURNING id''', [users]);
   var ids = idRows.map((row) => row['id']).toList();
 
-  // Alternative, using json1 functions directly
-  await db.execute('''
+  // Alternatively, using json1 functions directly.
+  var idRows2 = await db.execute('''
 INSERT INTO users(name, email)
 SELECT e.value ->> 'name', e.value ->> 'email' FROM json_each(?) e
 RETURNING id''', [users]);
 
-  // Select using "WHERE id IN ..."
+  // Select using "WHERE id IN ...".
   var queriedUsers = (await db.getAll(
           "SELECT id, name, email FROM users WHERE id IN (SELECT json_each.value FROM json_each(?)) ORDER BY name",
           [ids]))
@@ -67,14 +77,14 @@ RETURNING id''', [users]);
 
   print(queriedUsers);
 
-  // Bulk update using UPDATE FROM
+  // Bulk update using UPDATE FROM.
   await db.execute('''
 UPDATE users
   SET name = args.name, email = args.email
 FROM (${User.selectJsonData('?')}) as args
   WHERE users.id = args.id''', [queriedUsers]);
 
-  // Bulk delete using "WHERE id IN ..."
+  // Bulk delete using "WHERE id IN ...".
   await db.execute('''
 DELETE FROM users WHERE id IN (SELECT json_each.value FROM json_each(?))''',
       [queriedUsers.map((u) => u.id).toList()]);

example/linux_cli_example.dart

@@ -6,6 +6,7 @@ import 'package:sqlite3/sqlite3.dart' as sqlite;
 
 const defaultSqlitePath = 'libsqlite3.so.0';
 
+/// Custom factory to configure how the database is opened in each Isolate.
 class TestOpenFactory extends DefaultSqliteOpenFactory {
   String sqlitePath;
 
@@ -16,6 +17,8 @@ class TestOpenFactory extends DefaultSqliteOpenFactory {
 
   @override
   sqlite.Database open(SqliteOpenOptions options) {
+    // For details, see:
+    // https://pub.dev/packages/sqlite3#manually-providing-sqlite3-libraries
     sqlite_open.open.overrideFor(sqlite_open.OperatingSystem.linux, () {
       return DynamicLibrary.open(sqlitePath);
     });

pubspec.yaml

@@ -1,5 +1,5 @@
 name: sqlite_async
-description: High-performance asynchronous interface for SQLite.
+description: High-performance asynchronous interface for SQLite on Dart and Flutter.
 version: 0.1.0
 repository: https://github.com/journeyapps/sqlite_async.dart
 environment: