Choosing a runtime

comon_orm gives you one generated client shape across several runtime adapters. The important choice is not only the database engine, but also who owns rollout.

Quick matrix

PostgreSQL

Choose PostgreSQL when:

• the database is shared
• concurrent application access matters
• you need stronger in-place migration behavior than SQLite can offer
• enums, richer native types, and operational tooling matter

Typical runtime path:

final db = await ComonOrm.postgres();

Typical rollout path:

dart run comon_orm migrate dev --name 20260318_add_roles
dart run comon_orm migrate deploy

VM SQLite

Choose VM SQLite when:

• the app runs locally on Dart VM or the server
• the database is file-backed and simple to operate
• you want the same generated client shape as PostgreSQL with a smaller local footprint

Typical runtime path:

final db = await ComonOrm.sqlite();

Use the reviewed CLI flow when the SQLite file is shared or long-lived. For disposable local development data, explicit bootstrap can be enough.

Flutter SQLite

Choose Flutter SQLite when:

• the app owns a device-local SQLite file
• runtime uses the shared sqlite adapter metadata
• upgrades must happen on-device before the generated runtime opens the file

Typical runtime path:

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

This is intentionally different from the shared-database CLI workflow.

In-memory

Choose in-memory when:

• writing tests
• prototyping generated-client behavior
• validating relation semantics without filesystem or network setup

Typical runtime path:

final db = ComonOrm.inMemory();

This path uses generated runtime metadata and is usually the fastest route for unit and integration tests.

Continue with

• Runtime and adapters for normal runtime startup patterns
• Migrations for rollout decisions and recovery paths
• Testing for fast in-memory tests