Migration Guide

This page maps the older comon_orm API shape onto the current one.

Use it when upgrading existing apps, examples, or internal snippets.

High-level changes

• generated client class name is now ComonOrm
• provider openers now live on ComonOrm itself
• runtime, codegen, and migration imports are split more explicitly
• Flutter local SQLite no longer uses a separate Dart-only migration DSL
• reviewed .sql migrations are now the shared migration format across CLI and runtime

Rename map

Basic upgrade

Old generated client usage:

import 'generated/comon_orm_client.dart';

final db = await GeneratedComonOrmClientSqlite.open();

New generated client usage:

import 'generated/comon_orm_client.dart';

final db = await ComonOrm.sqlite();

Old in-memory test setup:

final db = GeneratedComonOrmClient.openInMemory();

New in-memory test setup:

final db = ComonOrm.inMemory();

Old PostgreSQL startup:

final db = await GeneratedComonOrmClientPostgresql.open();

New PostgreSQL startup:

final db = await ComonOrm.postgres();

Import changes

The public surface is narrower now.

Use:

• package:comon_orm/comon_orm.dart for runtime APIs
• package:comon_orm/codegen.dart for schema parsing, validation, and generator tooling
• package:comon_orm/migrations.dart for migration abstractions and artifact helpers
• package:comon_orm_sqlite/comon_orm_sqlite.dart for sqlite runtime
• package:comon_orm_sqlite/migrations.dart for sqlite CLI and schema tooling
• package:comon_orm_postgresql/comon_orm_postgresql.dart for postgresql runtime
• package:comon_orm_postgresql/migrations.dart for postgresql migration and schema tooling

If older code imported one broad barrel and used both runtime and tooling symbols, split those imports now.

Flutter local SQLite migration change

The biggest behavioral change is Flutter startup.

Older Flutter code often used app-side migration helpers like:

• SqliteFlutterMigrator
• SqliteFlutterMigration
• upgradeSqliteFlutterDatabase(...)

That path is gone.

Use reviewed .sql migrations instead:

import 'package:comon_orm_sqlite_flutter/comon_orm_sqlite_flutter.dart';

import 'generated/comon_orm_client.dart';

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);

Operationally this means:

1. create migrations through the normal CLI flow
2. bundle the reviewed migrations/ artifact tree into Flutter assets
3. apply them at startup with ComonOrm.migrate(...)
4. build the typed runtime client only after migration succeeds

CLI command notes

• dart run comon_orm check is the preferred schema validation command
• dart run comon_orm validate still exists as a compatibility alias
• migrate dev creates and applies the next reviewed .sql migration locally
• migrate deploy applies already-reviewed local migrations to shared environments

Migration checklist

When updating an older app or example:

1. Regenerate the client so the generated output becomes ComonOrm.
2. Replace old provider helper class calls with ComonOrm.inMemory(), ComonOrm.sqlite(...), or ComonOrm.postgres(...).
3. Split imports if runtime code was relying on tooling symbols from package:comon_orm/comon_orm.dart.
4. Remove Flutter-only migration DSL usage and switch to asset-backed reviewed SQL migrations.
5. Re-run the focused runtime and migration tests for the touched package.

When not to change startup shape

If you need to migrate before creating the typed client, open the adapter first and then construct ComonOrm(adapter: adapter) yourself.

That is expected for:

• Flutter local SQLite startup with bundled assets
• custom adapter factories
• advanced bootstrap flows where you need direct access to the adapter before delegates are used