Skip to main content

Installation

Requirements​

  • Dart SDK >= 3.0.0
  • A supported database driver package

Install the CLI​

The Ormed CLI manages migrations, seeders, and project scaffolding. You have two options for installation:

Install globally to keep your project's dependency tree clean.

dart pub global activate ormed_cli

Option B: Local Dependency​

Add to dev_dependencies to ensure the CLI version always matches your project.

dev_dependencies:
  ormed_cli: ^0.1.0-dev+1
info

Note: Adding ormed_cli as a local dependency will pull in all supported database drivers (SQLite, MySQL, Postgres) and their respective native dependencies.

Install Dependencies​

Add Ormed and at least one database driver to your pubspec.yaml:

dependencies:
  ormed: ^0.1.0-dev+1
  ormed_sqlite: ^0.1.0-dev+1

dev_dependencies:
  build_runner: ^2.4.0

Then run:

dart pub get

Initialize Project Files​

Scaffold the default config, migration registry, and seed stubs:

ormed init

(Or use dart run ormed_cli:ormed init if not installed globally).

Key outputs:

  • ormed.yaml — CLI + connection settings
  • lib/src/database/migrations.dart — migration registry
  • lib/src/database/seeders.dart — seeder registry

Project Structure​

A typical Ormed project structure looks like:

my_app/
├── lib/
│   ├── src/
│   │   ├── models/
│   │   │   ├── user.dart
│   │   │   ├── user.ormed.dart  (generated)
│   │   │   └── post.dart
│   │   └── database/
│   │       └── migrations/
│   │           ├── migrations.dart
│   │           └── m_20241201_create_users_table.dart
│   └── main.dart
├── ormed.yaml           (CLI configuration)
└── pubspec.yaml

Code Generation​

After defining your models, run the build runner to generate the ORM code:

# One-time build
dart run build_runner build

# Watch mode for development
dart run build_runner watch

This generates .ormed.dart files alongside your model files containing:

  • $ModelName - Tracked model class with change tracking
  • ModelNameOrmDefinition - Model metadata and static helpers
  • $ModelNamePartial - Partial entity for projections
  • ModelNameInsertDto / ModelNameUpdateDto - Data transfer objects

It also generates a centralized orm_registry.g.dart file with:

  • bootstrapOrm() - One-call setup: registry + factories + generated model wiring
  • buildOrmRegistry() - Creates a ModelRegistry with all models registered (lower-level)
  • registerOrmFactories() - Registers factories for Model.factory<T>() (when enabled)
  • registerModelEventHandlers() / registerModelScopes() - Registers generated wiring into the global bus/registries

Next Steps​