Skip to content

Seeding ​

Seeders fill your database with data: reference rows like roles and plans, an admin account, or a batch of fake posts for local development. Each seeder has a name, so you can run one setup step on its own or all of them together.

bash
npx holo make:seeder RolesSeeder
ts
import { defineSeeder } from '@holo-js/db'
import Role from '../../models/Role'

export default defineSeeder({
  name: 'roles',
  async run() {
    await Role.firstOrCreate({ slug: 'admin' }, { name: 'Admin' })
    await Role.firstOrCreate({ slug: 'editor' }, { name: 'Editor' })
  },
})
bash
npx holo seed

Writing seeders ​

make:seeder creates a file in server/db/seeders. The name comes from the file name without the Seeder suffix, in snake case: RolesSeeder becomes roles, DemoContentSeeder becomes demo_content. You use this name with --only and call().

Inside run(), use your models or the query builder as usual. run() also receives a context:

PropertyWhat it is
dbThe database connection
schemaThe schema builder, same as in migrations
call(...names)Runs other seeders by name
ts
import { defineSeeder } from '@holo-js/db'

export default defineSeeder({
  name: 'settings',
  async run({ db }) {
    await db.table('settings').insert({ key: 'site_name', value: 'My Blog' })
  },
})

TIP

Use firstOrCreate() or updateOrCreate() for reference data so running the seeder twice doesn't create duplicates.

Using factories ​

Factories are the easiest way to create lots of realistic records:

ts
import { defineSeeder } from '@holo-js/db'
import PostFactory from '../factories/PostFactory'
import UserFactory from '../factories/UserFactory'

export default defineSeeder({
  name: 'demo_content',
  async run() {
    await UserFactory
      .count(5)
      .has(PostFactory.count(3), 'posts')
      .create()
  },
})

Calling other seeders ​

A root seeder can run the others in a fixed order with call():

ts
import { defineSeeder } from '@holo-js/db'

export default defineSeeder({
  name: 'database',
  async run({ call }) {
    await call('roles')
    await call('settings')
    await call('demo_content')
  },
})

Run it on its own with --only:

bash
npx holo seed --only database

WARNING

npx holo seed without --only runs every seeder in server/db/seeders. If a root seeder calls the others, they run twice. Use --only database when you rely on a root seeder.

Running seeders ​

bash
npx holo seed
npx holo seed --only roles,settings

Reset the database and seed it in one step:

bash
npx holo migrate:fresh --seed --only database
FlagEffect
--only <names>Run only these seeders. Comma-separated, or repeat the flag
--quietlyTurn off model events and observers while seeding
--forceSkip the production confirmation

Mass assignment ​

Seeders run without mass-assignment guards, as Laravel's db:seed does, so a seeder can set any column, including ones that aren't in fillable. Don't pass request input to a seeder. Wrapping seeder writes in unguarded() isn't needed.

Transactions ​

Each seeder runs in a transaction. If it throws, everything it wrote rolls back. Seeders started with call(), and any model writes inside them, join the same transaction, so a failing root seeder undoes the whole run.

Seeding in production ​

When the environment is production, holo seed asks you to confirm before it writes anything. The environment comes from APP_ENV and is production when APP_ENV isn't set. Without a terminal, the command stops with an error, so pass --force in scripts when you really mean it:

bash
npx holo seed --only roles --force

Seeder reference ​

defineSeeder() ​

Declares a seeder. It takes an object with a name (string) and a run(context) function, and returns that object.

ts
import { defineSeeder } from '@holo-js/db'

export default defineSeeder({
  name: 'settings',
  async run({ db }) {
    await db.table('settings').insert({ key: 'site_name', value: 'My Blog' })
  },
})

call() ​

Runs other seeders by name, in the order you list them, inside the current seeder's transaction. It is available on the context passed to run().

ts
import { defineSeeder } from '@holo-js/db'

export default defineSeeder({
  name: 'database',
  async run({ call }) {
    await call('roles', 'settings')
  },
})

Context properties ​

run() receives these properties:

PropertyTypeMeaning
dbconnectionThe active database connection. Use db.table() for query builder calls.
schemaschema builderCreates and changes tables, same as in migrations

Seed options ​

The seeder run accepts these options. The CLI sets them from the flags in Running seeders.

OptionMeaning
onlyNames of the seeders to run. Unknown names throw.
quietlyTurn off model events and observers while seeding
forceAllow seeding when environment is production
environmentEnvironment name used for the production check. The CLI passes the application environment.

Next steps ​

Released under the MIT License.