# Seeder A `Seeder` populates a table with reference or bootstrap rows: the permission catalogue, the built-in roles, the first administrator. It is not a migration: it runs on demand, it is idempotent, and it never changes the schema. ## Contract ```php interface Seeder { public function name(): string; public function run(Orm $orm): void; } ``` - `name()` is what you type on the command line and what the runner orders by. Keep it short and unique: `permissions`, `roles`, `admin-user`. - `run()` receives the `Orm`, so a seeder writes through repositories like any other consumer. It must be safe to run twice: an insert of an existing row is a no-op, not an error. - A seeder throws nothing it cannot explain. A failure stops the batch and is reported. ## Runner `Camelia\Orm\Seeding\SeederRunner` executes an ordered list of seeders inside one transaction: ```php $runner = new SeederRunner($orm, [new PermissionsSeeder(), new RolesSeeder(), new AdminSeeder()]); $report = $runner->run(); ``` Every seeder runs in the same transaction: either the whole batch applies or none of it does. The report tells you what happened per seeder. ## Writing a seeder Subclass `AbstractSeeder` to get idempotent helpers instead of hand-rolling `findOrCreate` calls: ```php final class PermissionsSeeder extends AbstractSeeder { public function name(): string { return 'permissions'; } public function run(Orm $orm): void { $repository = $orm->repository(PermissionModel::class); foreach (Permission::cases() as $permission) { $this->seedOnce($repository, ['code' => $permission->value], [ 'module' => $permission->module(), 'action' => $permission->action(), ]); } } } ``` `seedOnce()` inserts when the criteria match nothing and reports whether it did. It never updates an existing row, because a seeder that silently overwrites data the user edited is a footgun. ## Ordering Seeders run in the order you pass them. When a seeder depends on rows another one creates (roles need permissions), pass them in dependency order and let the transaction protect you.