English | Русский

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.