Skip to main content

Quick Start

This guide will walk you through creating a simple Ormed application with a User model. If you are integrating into an existing app, use Adopt Ormed In An Existing Project instead.

Prerequisites​

  • You completed Installation
  • You can run dart pub get and dart run build_runner build in your app

What You’ll Learn​

  • How to scaffold runtime config with ormed init
  • How models, migrations, seeders, and generated code connect
  • How to boot DataSource and run basic CRUD

Step Outcome​

By the end of this page, you should have:

  • A generated runtime datasource scaffold
  • A User model with generated ORM artifacts
  • A migration + seeder applied locally
  • A runnable app that performs create/read/update/delete

Command Flow (One Pass)​

dart run ormed_cli:ormed init
dart run build_runner build
dart run ormed_cli:ormed make:migration --name create_users_table --create --table users
dart run ormed_cli:ormed migrate
dart run ormed_cli:ormed make:seeder --name UserSeeder
dart run ormed_cli:ormed seed
dart run lib/main.dart

Scaffold the Project (CLI)​

From your app root:

dart run ormed_cli:ormed init

This creates:

  • lib/src/database/config.dart (runtime datasource options)
  • lib/src/database/datasource.dart (DataSource entrypoint)
  • lib/src/database/migrations.dart (registry)

Optional:

  • ormed.yaml when you run dart run ormed_cli:ormed init --with-config
  • lib/src/database/seeders.dart and seeders/database_seeder.dart when you run dart run ormed_cli:ormed init --with-seeders

Generated starter files:

Generated runtime config (code-first default):

const String defaultDataSourceConnection = 'default';

/// Connections baked into this generated scaffold.
const List<String> generatedDataSourceConnections = <String>['default'];
DataSourceOptions buildDataSourceOptions({String? connection}) {
  final env = OrmedEnvironment.fromDirectory(Directory.current);
  final registry = bootstrapOrm();
  final selectedConnection = (connection ?? defaultDataSourceConnection).trim();
  switch (selectedConnection) {
    case 'default':
      final path = env.string(
        'DB_PATH',
        fallback: 'database/ormed_examples.sqlite',
      );
      return registry.sqliteFileDataSourceOptions(path: path, name: 'default');
    default:
      throw ArgumentError.value(
        selectedConnection,
        'connection',
        'Unknown generated datasource connection. Expected one of: default',
      );
  }
}
Map<String, DataSourceOptions> buildAllDataSourceOptions() {
  final options = <String, DataSourceOptions>{};
  for (final connection in generatedDataSourceConnections) {
    options[connection] = buildDataSourceOptions(connection: connection);
  }
  return options;
}

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.orm.dart with the generated $User class and helpers.

Create a Migration​

Create a migration for your table:

dart run ormed_cli:ormed make:migration --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:seeder --name UserSeeder

This command bootstraps the seed scaffold automatically if it does not exist yet.

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

In your application code, use the generated createDataSource() helper to initialize the ORM.

import 'package:ormed/ormed.dart';
import 'src/database/datasource.dart'; // Generated by ormed init

void main() async {
  // 1. Create the DataSource using generated runtime options
  final ds = createDataSource();

  // 2. Initialize connections
  await ds.init();

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

Run Your App​

dart run lib/main.dart

Output:

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

Exact IDs/counts may differ, but you should see successful CRUD behavior without errors.

Next Steps​