Skip to main content

Installation

Who This Is For​

Use this page if you are setting up Ormed in a project for the first time.

Prerequisites​

  • A Dart environment where you can run dart pub and dart run

Requirements​

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

What You’ll Learn​

  • How to install Ormed runtime + CLI dependencies
  • What ormed init generates
  • Which files are required for the first runnable app

Step Outcome​

By the end of this page, you should have:

  • ormed + one driver installed
  • ormed init scaffold files in lib/src/database/*
  • Working codegen (dart run build_runner build)
  • A clear next step: Quick Start or Adopt Existing Project

Install In Order​

dart pub get
dart run ormed_cli:ormed init --no-interaction
dart run build_runner build --delete-conflicting-outputs

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.2.0
info

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

Choose global when you prefer a thin project dependency tree. Choose local when you want deterministic CLI versions per repo.

Install Dependencies​

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

dependencies:
  ormed: ^0.2.0
  ormed_sqlite: ^0.2.0

dev_dependencies:
  build_runner: ^2.4.0

Then run:

dart pub get

Initialize Project Files​

Scaffold code-first runtime datasource config and migration registry:

ormed init

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

Key outputs:

  • lib/src/database/config.dart — Runtime DataSource options helpers
  • lib/src/database/datasource.dart — Main ORM entry point
  • lib/src/database/migrations.dart — migration registry
  • lib/src/database/orm_registry.g.dart — generated registry after build_runner

Optional:

  • ormed.yaml — run ormed init --with-config when you want explicit config file driven CLI connection blocks.
  • lib/src/database/seeders.dart + lib/src/database/seeders/database_seeder.dart — run ormed init --with-seeders (or ormed init --only=seeders) when you want explicit seed scaffold upfront.

Verify Installation​

Run one of these:

ormed --help
dart run ormed_cli:ormed --help

Then verify generated files exist under lib/src/database/.

Project Structure​

A typical Ormed project structure looks like:

my_app/
├── lib/
│   ├── src/
│   │   ├── models/
│   │   │   ├── user.dart
│   │   │   ├── user.orm.dart  (generated)
│   │   │   └── post.dart
│   │   └── database/
│   │       ├── config.dart
│   │       ├── datasource.dart
│   │       ├── orm_registry.g.dart (generated)
│   │       ├── migrations.dart
│   │       └── migrations/
│   │           └── m_20241201_create_users_table.dart
│   └── main.dart
└── 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 .orm.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 lib/src/database/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​