Skip to main content

Adopt Ormed In An Existing Project

This guide is for teams integrating Ormed into an already running Dart service.

Before you start: Installation; Familiarity with your current DB schema and deployment flow.

Integration Strategy​

Use this sequence:

  1. Add Ormed packages and generate code.
  2. Introduce a DataSource bootstrap path behind a small adapter layer.
  3. Move one model/query path at a time.
  4. Adopt migrations only after deciding ownership boundaries.

Safety Rules For Existing Systems​

  1. Keep old and new paths side-by-side during rollout.
  2. Port read paths before write-heavy paths.
  3. Add regression tests for each ported endpoint/repository.
  4. Decide migration ownership once, then document it in-repo.

1. Add Dependencies​

Pick your runtime driver and install:

dependencies:
  ormed: ^0.4.0
  ormed_sqlite: ^0.4.1 # or ormed_postgres / ormed_mysql / ormed_d1

dev_dependencies:
  build_runner: ^2.10.5
  ormed_cli: ^0.3.1
dart pub get

2. Scaffold Runtime Files​

From project root:

dart run ormed_cli:ormed init

This adds lib/src/database/config.dart and lib/src/database/datasource.dart so runtime wiring is code-first by default. Seeder scaffold is optional and can be added later with ormed init --only=seeders (or by running ormed make:seeder).

3. Add Ormed Models Gradually​

Create/annotate model files in lib/src/models/ and generate:

dart run build_runner build --delete-conflicting-outputs

Generated output (*.orm.dart + orm_registry.g.dart) stays alongside your existing code and can be adopted incrementally.

4. Bootstrap DataSource In App Startup​

Wire Ormed once during app startup:

import 'src/database/datasource.dart';

Future<void> main() async {
  final ds = createDataSource();
  await ds.init();

  // existing application startup...
}

5. Choose Migration Ownership​

For existing databases, pick one approach and document it in your repo:

  • Ormed-owned going forward:
    • keep historical schema as-is
    • add a baseline migration entry representing current state
    • use ormed make:migration / ormed migrate for all new changes
  • Externally managed schema:
    • continue current migration tool
    • use Ormed primarily for models/queries/runtime access

If your schema is already mature, start with externally managed migrations and switch only when your team agrees on ownership and release process.

6. Move Endpoints In Slices​

Do not migrate everything at once. Port one endpoint/repository at a time, validate behavior, then proceed.

Recommended order:

  1. Read-only queries
  2. Simple writes
  3. Transaction-heavy paths

Verify Before Expanding Scope​

  • One endpoint fully moved (query + write + tests)
  • Startup/teardown remains stable in all environments
  • No schema drift introduced by accidental migration execution

Read This Next​