Quick Start

This guide will walk you through creating a simple Ormed application with a User model.

Scaffold the Project (CLI)

From your app root:

dart run ormed_cli:ormed init

This creates:

• ormed.yaml with database + migration settings
• lib/src/database/migrations.dart (registry)
• lib/src/database/seeders.dart and seeders/database_seeder.dart

Generated starter files:

ormed.yaml

driver:
  type: sqlite
  options:
    database: database.sqlite
migrations:
  directory: lib/src/database/migrations
  registry: lib/src/database/migrations.dart
  ledger_table: orm_migrations
  schema_dump: database/schema.sql
seeds:
  directory: lib/src/database/seeders
  registry: lib/src/database/seeders.dart

migrations.dart

These are the three pieces the CLI maintains: imports, the entry list, and buildMigrations().

// <ORM-MIGRATION-IMPORTS>
// </ORM-MIGRATION-IMPORTS>

final List<MigrationEntry> _entries = [
  // <ORM-MIGRATION-REGISTRY>
  // </ORM-MIGRATION-REGISTRY>
];

/// Build migration descriptors sorted by timestamp.
List<MigrationDescriptor> buildMigrations() =>
    MigrationEntry.buildDescriptors(_entries);

seeders.dart

Seed registries follow the same pattern: imports + registrations + a runnable entrypoint.

import 'database_seeder.dart';
// <ORM-SEED-IMPORTS>
// </ORM-SEED-IMPORTS>

final List<SeederRegistration> _seeders = <SeederRegistration>[
  // <ORM-SEED-REGISTRY>
  SeederRegistration(
    name: 'AppDatabaseSeeder',
    factory: (context) => AppDatabaseSeeder(context.connection),
  ),
  // </ORM-SEED-REGISTRY>
];

Future<void> runProjectSeeds(
  OrmConnection connection, {
  List<String>? names,
  bool pretend = false,
}) => runSeedRegistryOnConnection(
  connection,
  _seeders,
  names: names,
  pretend: pretend,
);

Future<void> main(List<String> args) =>
    runSeedRegistryEntrypoint(args: args, seeds: _seeders);

Create Your Model

Create lib/src/models/user.dart:

// #region intro-model
import 'package:ormed/ormed.dart';

part 'user.orm.dart';

@OrmModel(table: 'users')
class User extends Model<User> {
  const User({
    required this.id,
    required this.email,
    this.name,
    this.createdAt,
  });

  @OrmField(isPrimaryKey: true, autoIncrement: true)
  final int id;

  final String email;
  final String? name;
  final DateTime? createdAt;
}

// #endregion intro-model

Generate ORM Code

Run the build runner:

dart run build_runner build

This creates user.ormed.dart with the generated $User class and helpers.

Create a Migration

Create a migration for your table:

dart run ormed_cli:ormed make --name create_users_table --create --table users

Edit the generated file in lib/src/database/migrations/ to add columns:

void up(SchemaBuilder schema) {
  schema.create('users', (table) {
    table.id();
    table.string('name');
    table.string('email').unique();
    table.timestamps();
  });
}

Apply the migration:

dart run ormed_cli:ormed migrate

Seed the Database

Create a seeder:

dart run ormed_cli:ormed make --name UserSeeder --seeder

Add data in lib/src/database/seeders/user_seeder.dart:

Future<void> run() async {
  await seed<User>([
    {'name': 'John Doe', 'email': 'john@example.com'},
  ]);
}

Run the seeders:

dart run ormed_cli:ormed seed

Set Up the Database (SQLite)

Setup

In your application code, use bootstrapOrm() to register all generated models and metadata automatically.

import 'package:ormed/ormed.dart';
import 'package:ormed_sqlite/ormed_sqlite.dart';
import 'orm_registry.g.dart'; // Generated by ormed

void main() async {
  // 1. Bootstrap the registry
  final registry = bootstrapOrm();

  // 2. Initialize DataSource
  final ds = DataSource(DataSourceOptions(
    driver: SqliteDriverAdapter.file('database.sqlite'),
    registry: registry,
  ));
  await ds.init();

  // 3. Query your models
  final users = await ds.query<User>().get();
  print('Found ${users.length} users');
}

CRUD

Use the generated tracked model ($User) with the repository and query builder:

Future<void> useOrm(DataSource dataSource) async {
  final userRepo = dataSource.repo<$User>();

  // Insert a user
  final user = await userRepo.insert(
    $User(id: 0, email: 'john@example.com', name: 'John Doe'),
  );
  print('Created user: ${user.id}');

  // Query users
  final users = await dataSource
      .query<$User>()
      .whereEquals('name', 'John Doe')
      .get();
  print('Found users: ${users.length}');

  // Update a user
  user.setAttribute('name', 'John Smith');
  final updated = await userRepo.update(user);
  print('Updated name: ${updated.name}');

  // Delete a user
  await userRepo.delete({'id': user.id});
  print('User deleted');
}

Run Your App

dart run lib/main.dart

Output:

Created user: 1
Found users: 1
Updated name: John Smith
User deleted

Next Steps

• Defining Models - Learn about model annotations and fields
• Query Builder - Master the fluent query API
• Repository Pattern - CRUD operations with flexible inputs
• Migrations - Schema management and versioning