Skip to main content

Quick Start

This guide walks through the generated-model path: a User model, migration, seeder, and typed queries. If you want to connect first and decide on models later, start with Direct Database Access. If you are integrating into an existing app, use Adopt Ormed In An Existing Project instead.

Before you start: You completed Installation; You completed the Code Generation tooling setup; You can run dart run ormed_cli:ormed as described in CLI Overview.

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;
}

Generate ORM Code​

Run the build runner:

dart run build_runner build --delete-conflicting-outputs

This creates user.orm.dart with the generated $User class and helpers. For watch mode, builder configuration, generated registry details, and verification guidance, see Code Generation.

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​