
# Runners

A runner is a bean whose `run` method is called once the application has started: database migrations, a cache warm-up, the job of a command-line tool. Runners run one after another, sorted by `@Order`, as in Spring Boot.

## Why

Start-up work needs every bean to exist, and it often has to happen in a given order: the schema must be migrated before the warm-up reads it. A runner is called after the context is ready, and the next one starts only when the previous one (its `Future` included) is done. A failing runner stops the application with a report, instead of leaving it half started.

## Example

```dart
// The schema must be up to date before anything else touches the database.
@Component()
@Order(1)
class Migrations implements ApplicationRunner {
  Migrations(this.db);

  final Database db;

  @override
  Future<void> run(ApplicationArguments args) => db.migrate(); // awaited
}

// Starts only after Migrations has finished.
@Component()
@Order(2)
class Warmup implements ApplicationRunner {
  Warmup(this.catalog);

  final Catalog catalog;

  @override
  Future<void> run(ApplicationArguments args) => catalog.loadBestsellers();
}

// A command-line job: dart run bin/main.dart --dry-run books.csv
@Component()
class Importer implements ApplicationRunner {
  Importer(this.books);

  final BookStore books;

  @override
  Future<void> run(ApplicationArguments args) async {
    final dryRun = args.containsOption('dry-run');
    for (final file in args.nonOptionArgs) {
      await books.importCsv(file, save: !dryRun);
    }
  }
}
```

## The two kinds

| Interface | `run` receives | Use |
|---|---|---|
| `ApplicationRunner` | `ApplicationArguments`: options and plain arguments, parsed | Most runners |
| `CommandLineRunner` | `List<String>`: the arguments exactly as `main` got them | Code that parses arguments itself |

Both may return `void` or a `Future`. A bean that implements both is called as both.

## Order and timing

- Runners are sorted by `@Order` (or `Ordered`), lowest first; runners without an order come last.
- Each runner finishes, its `Future` included, before the next starts.
- They run after `ApplicationStartedEvent` and after any `AsyncStartup` bean (the web server listening), and before `ApplicationReadyEvent`.
- If the context is closed meanwhile, the remaining runners are skipped.
- `runApplication` returns once the synchronous part is done; asynchronous runners then go on. `await runApplicationAsync(args)` completes after the last runner.

## When a runner fails

The failure is reported as `Application run failed` with the error, `ApplicationFailedEvent` is published and the context is closed. With `runApplication`, an asynchronous failure is rethrown outside any `try`, which ends the program with a non-zero code. With `runApplicationAsync`, the returned `Future` fails.

An exit code for the failure comes from `ExitCodeExceptionMapper` beans, or from the exception itself when it implements `ExitCodeGenerator`; see [Shutdown and exit codes](shutdown.md).

## ApplicationArguments

`SpringApplication` parses the arguments once and registers the result as a bean, so any bean can inject it.

| Member | Meaning |
|---|---|
| `sourceArgs` | The arguments as `main` received them |
| `optionNames` | The names of the options given (`dry-run` for `--dry-run`) |
| `containsOption(name)` | Whether the option was given, with or without a value; the name without dashes |
| `getOptionValues(name)` | The values in order (`['a', 'b']` for `--tag=a --tag=b`); `[]` for a bare `--name`; `null` when not given |
| `nonOptionArgs` | The plain arguments: those not starting with `--`, and everything after a lone `--` |

Options are `--name=value` or a bare `--name`; only the first `=` separates. `-v` is a plain argument. Options are also properties, so `--server.port=8081` sets `server.port`; most settings are read with `@Value` or `@ConfigurationProperties` rather than from here.

## Runners and hot reload

When a Flutter hot reload restarts the context (beans or configuration changed), the runners run again by default, like after a Spring Boot DevTools restart. `reloadApplication(context, runners: false)` restarts the beans without repeating migrations, analytics events or network calls. See [Hot reload](hot-reload.md).

## In Spring (Java)

```java
@Component
@Order(1)
class Migrations implements ApplicationRunner {
  public void run(ApplicationArguments args) { db.migrate(); }
}
```

The same interfaces and order. A runner returning a `Future` is awaited before the next one, which Java has no need for.

## See also

- [SpringApplication](spring-application.md)
- [Events](events.md)
- [Shutdown and exit codes](shutdown.md)
- [Command line](configuration/sources.md)
