Database Seeding

Arquebus and by extension H3ravel supports database seeding with data using seeder classes. In H3ravel All seeder classes are stored in the src/database/seeders directory and by default, a DatabaseSeeder class has been defined for you. From this class, you may use the call method to run other seeder classes, allowing you to control the seeding order. This is a little bit different when using Arquebus directly as you have more control over where seeder classes will be stored. You should set the directory where you want seeder classes to be stored in the seeders property of the arquebus.config.[ts|js] file, by default seeders will be stored in the seeders directory as you can see in the config.

arquebus.config.ts

export default defineConfig({
  ...
  seeders: {
    path: './seeders',
  },
  ...
});

Writing Seeders

To generate a seeder, call the make:seeder Musket or Arquebus CLI command. All seeders generated by H3ravel will be placed in the src/database/seeders directory and in your configured directory (Default: migrations) when generated with the arquebus CLI:

musket

$ npx musket make:seeder UserSeeder

arquebus

$ npx arquebus make:seeder UserSeeder

A seeder class only contains one method by default: run. This method is called when the db:seed Musket or Arquebus CLI command is called. Within the run method, you may insert data into your database however you wish. You may use the query builder to manually insert data [or you may use Arquebus model factories - WIP].

Let's modify the default DatabaseSeeder class and add a database insert statement to the run method (H3ravel):

import type { QueryBuilder } from '@h3ravel/arquebus';
import { DB, Seeder } from '@h3ravel/arquebus';
import { Hash } from '@h3ravel/hashing';

export default class DatabaseSeeder extends Seeder {
  /**
   * Run the database seeds.
   */
  async run() {
    await DB.table('users').insert({
      name: 'John Does',
      email: 'dj@x.com',
      password: await Hash.make('password'),
    });
  }
}

Calling Additional Seeders

Within the DatabaseSeeder class, you may use the call method to execute additional seed classes. Using the call method allows you to break up your database seeding into multiple files so that no single seeder class becomes too large. The call method accepts an array of seeder classes that should be executed:

import UserSeeder from './user_seeder';
import PostSeeder from './post_seeder';
import CommentSeeder from './comment_seeder';

export default class DatabaseSeeder extends Seeder {
  /**
   * Run the database seeds.
   */
  async run() {
    this.call([UserSeeder, PostSeeder, CommentSeeder]);
  }
}

Running Seeders

You may execute the db:seed Musket command to seed your database. By default, the db:seed command runs the DatabaseSeeder class from database/seeders/database_seeder, which may in turn invoke other seed classes. However, you may use the --class option to specify a specific seeder class to run individually:

musket

$ npx musket db:seed UserSeeder

$ npx musket db:seed --class=UserSeeder

arquebus

$ npx arquebus db:seed UserSeeder

$ npx arquebus db:seed UserSeeder --class=UserSeeder

You may also seed your database using the migrate:fresh command in combination with the --seed option, which will drop all tables and re-run all of your migrations. This command is useful for completely re-building your database. The --seeder option may be used to specify a specific seeder to run:

musket

$ npx musket migrate:fresh --seed

$ npx musket migrate:fresh --seed --seeder=UserSeeder

arquebus

$ npx arquebus migrate:fresh --seed

$ npx arquebus migrate:fresh --seed --seeder=UserSeeder

Forcing Seeders to Run in Production

Some seeding operations may cause you to alter or lose data. In order to protect you from running seeding commands against your production database, you will be prompted for confirmation before the seeders are executed in the production environment. To force the seeders to run without a prompt, use the --force flag:

musket

$ npx musket db:seed --force

arquebus

$ npx arquebus db:seed --force