Migration & Seeding Events

Migrations and seeders emit structured events through the shared EventBus. Subscribe once to stream progress to logs, metrics, or tracing.

:::note Snippet context The snippets below are split into “subscribe” and “run” pieces so you can reuse the listener wiring in your own bootstrap code. :::

Migration Lifecycle

Events (all emitted by MigrationRunner):

• MigrationBatchStartedEvent / MigrationBatchCompletedEvent
• MigrationStartedEvent / MigrationCompletedEvent
• MigrationFailedEvent (includes error and stackTrace)

Example listener + runner setup:

Subscribe

  bus.on<MigrationBatchStartedEvent>((event) {
    print('Migration batch ${event.batch} started');
  });

  bus.on<MigrationStartedEvent>((event) {
    print('Applying ${event.id}');
  });

  bus.on<MigrationCompletedEvent>((event) {
    print('Applied ${event.id} in ${event.duration.inMilliseconds}ms');
  });

  bus.on<MigrationFailedEvent>((event) {
    print('Failed ${event.id}: ${event.error}');
  });

Run

  final descriptors = MigrationEntry.buildDescriptors([
    MigrationEntry(
      id: MigrationId.parse('m_20241201000000_create_users_table'),
      migration: const CreateUsersTable(),
    ),
  ]);

  final runner = MigrationRunner(
    schemaDriver: schemaDriver,
    ledger: SqlMigrationLedger(schemaDriver, tableName: '_orm_migrations'),
    migrations: descriptors,
    events: bus,
  );

  await runner.applyAll();

Seeding Lifecycle

Events (emitted by SeederRunner and database seeders):

• SeedingStartedEvent / SeedingCompletedEvent
• SeederStartedEvent / SeederCompletedEvent
• SeederFailedEvent

Example with a custom seeder and event hooks:

Define a seeder

class DemoUserSeeder extends DatabaseSeeder {
  DemoUserSeeder(super.connection);

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

Subscribe

  bus.on<SeedingStartedEvent>((event) {
    print('Seeding started: ${event.seederNames.join(', ')}');
  });

  bus.on<SeederStartedEvent>((event) {
    print('Running seeder ${event.seederName} (${event.index}/${event.total})');
  });

  bus.on<SeederCompletedEvent>((event) {
    print('Seeder ${event.seederName} finished in ${event.duration}');
  });

  bus.on<SeederFailedEvent>((event) {
    print('Seeder ${event.seederName} failed: ${event.error}');
  });

  bus.on<SeedingCompletedEvent>((event) {
    print('Seeding complete (${event.count} seeders) in ${event.duration}');
  });

Run

  final runner = SeederRunner(events: bus);
  await runner.run(
    connection: dataSource.connection,
    seeders: const [
      SeederRegistration(name: 'DemoUserSeeder', factory: DemoUserSeeder.new),
    ],
  );

Tips:

• Use the same EventBus for migrations, seeders, and runtime queries to correlate logs.
• SeederFailedEvent fires before the error is rethrown—log here, then let your process fail.
• Combine with pretend: true on SeederRunner.run to capture SQL without mutating the database.

Verify Event Stream

1. Run one migration batch and confirm batch + per-migration events are emitted.
2. Run one seed flow and confirm start/completion/failure hooks.
3. Confirm failed events include enough context for alerting.

Read This Next

• Running Migrations
• Observability
• CLI Migrations