comon_orm_sqlite_flutter

comon_orm_sqlite_flutter is the Flutter-oriented SQLite package for comon_orm.

It now primarily exists to provide Flutter-specific migration loading on top of the shared runtime APIs, while comon_orm_sqlite remains the source of truth for SQLite runtime, CLI workflows, migrations, and introspection.

AI Documentation

Documentation

Comon | DOCS

Why A Separate Package

This package is separate on purpose.

The existing comon_orm_sqlite package already owns the current sqlite3-based VM runtime, CLI entrypoints, migration helpers, introspection, and file-system-oriented workflows. Flutter and browser targets need a different runtime bootstrap shape and much stricter separation from VM-only concerns.

Keeping Flutter support separate avoids turning one SQLite package into a mixed surface that tries to serve runtime embedding, CLI tooling, and migration workflows for very different platforms at once.

In practice the split is:

comon_orm_sqlite: Dart VM, CLI, migrations, introspection, local tooling
comon_orm_sqlite_flutter: Flutter asset loading for runtime migrations

This decision was made to keep platform boundaries explicit, not because SQLite itself is unavailable on web.

Current Status

This package is in active development.

Today it provides:

AssetsMigrationReader for loading reviewed SQL migrations from Flutter assets
migrationReaderFromAssets(...) as a convenience wrapper that returns a runtime MigrationReader
shared manifest-based discovery through assets/migrations/manifest.json
compatibility with the generated ComonOrm.migrate(...) runtime API

Implementation phases are tracked in PLAN.md.

Quick Start

Add dependencies:

dependencies:
  comon_orm: ^0.0.1-alpha.3
  comon_orm_sqlite_flutter: ^0.0.1-alpha.3

Load reviewed migrations from Flutter assets and apply them during startup:

import 'package:comon_orm_sqlite_flutter/comon_orm_sqlite_flutter.dart';

import 'generated/comon_orm_client.dart';

Future<void> main() async {
  final adapter = await SqliteDatabaseAdapter.openFromGeneratedSchema(
    schema: ComonOrm.runtimeSchema,
    databasePath: 'app.db',
  );

  try {
    await ComonOrm.migrate(
      adapter: adapter,
      migrations: migrationReaderFromAssets('assets/migrations'),
    );

    final db = ComonOrm(adapter: adapter);
    final created = await db.todo.create(
      data: TodoCreateInput(title: 'Ship Flutter runtime migrations'),
    );

    print(created.title);
  } finally {
    await adapter.close();
  }
}

Declare the migration assets in your Flutter app so manifest.json and each migration directory are bundled:

flutter:
  assets:
    - assets/migrations/manifest.json
    - assets/migrations/

manifest.json is now refreshed automatically by the file-backed migration services when a new migration draft is written.

Runtime Paths

Preferred runtime path: ComonOrm.sqlite(...) from generated clients
Preferred migration path: ComonOrm.migrate(...) plus migrationReaderFromAssets(...)
Package scope: Flutter asset loading plus shared sqlite runtime re-exports

Bundled Runtime Migrations

The recommended Flutter path is now to reuse the reviewed sqlite migration artifacts produced by the normal CLI workflow and load them from Flutter assets.

Typical startup shape:

import 'package:comon_orm_sqlite_flutter/comon_orm_sqlite_flutter.dart';

import 'generated/comon_orm_client.dart';

Future<void> main() async {
  final adapter = await SqliteDatabaseAdapter.openFromGeneratedSchema(
    schema: ComonOrm.runtimeSchema,
    databasePath: 'app.db',
  );

  await ComonOrm.migrate(
    adapter: adapter,
    migrations: migrationReaderFromAssets('assets/migrations'),
  );

  final db = ComonOrm(adapter: adapter);

  try {
    print(await db.todo.count());
  } finally {
    await db.close();
  }
}

Practical rules:

use CLI-reviewed migrations for shared, staging, production, and important device-local SQLite data
prefer reset over migration history when local data is disposable
bundle the reviewed migrations/ artifact tree into assets/migrations/
keep migration application first and typed runtime usage second
do not edit old migration artifacts after they were applied on real devices

Scope

The existing comon_orm_sqlite package remains the source of truth for CLI, migration, and introspection flows.
Flutter and web runtime support are being added here incrementally instead of retrofitting those constraints into the VM-oriented SQLite package.
The package now participates in the root pub workspace and monorepo validation scripts.