Seeding
Seeding means putting data into your database with code instead of by hand: the roles your app needs, the first admin user, a list of countries, or a few hundred fake customers so the screens look real while you build. A seeder is a small file with a run() function that creates those rows. Seeders live in database/seeders/, one file per table, named like post.seeder.ts.
The commands at a glance
Section titled “The commands at a glance”| You want to | Run | Status |
|---|---|---|
| Create a table with a seeder and a factory | node strut make:migration create_posts_table --seeder |
Prototype |
| Create a seeder for an existing table | node strut make:seeder PostSeeder |
Coming in 0.2 |
| Create a model with a seeder | node strut make:model Post -s |
Coming in 0.2 |
| Run every seeder | node strut db:seed |
Prototype |
| Run one seeder | node strut db:seed --class=PostSeeder |
Coming in 0.2 |
| Seed in production, on purpose | node strut db:seed --force |
Coming in 0.2 |
| Migrate, then run the seeders | node strut migrate --seed |
Prototype |
| Start over: drop everything, migrate, seed | node strut migrate:fresh --seed |
Coming in 0.2 |
The smallest seeder, step by step
Section titled “The smallest seeder, step by step”-
Ask for a seeder when you create the table:
Terminal window node strut make:migration create_posts_table --seederWhat you’ll see (something like this; the exact wording isn’t final):
Created database/migrations/2026_11_15_093000_create_posts_table.tsCreated app/models/post.tsCreated database/seeders/post.seeder.tsCreated database/factories/post.factory.tsNext: add your columns to the migration, then run `node strut migrate`.--seederalso creates the factory, because seeders usually use one, and registers the seeder indatabase/seeders/database.seeder.ts. -
Open the seeder. It’s empty:
database/seeders/post.seeder.ts import { defineSeeder } from '@strutvane/framework'import { Post } from '../../app/models/post.ts'/** Seeds the `posts` table. */export default defineSeeder({after: ['users'],async run() {// Create a few rows, for example:// await Post.factory().count(10).create()},})afterlists the tables whose seeders must run first. Strutvane fills it in from your migration’s foreign keys (posts.author_idpoints atusers). -
Fill in
run():database/seeders/post.seeder.ts import { defineSeeder } from '@strutvane/framework'import { Post } from '../../app/models/post.ts'import { User } from '../../app/models/user.ts'/** Seeds the `posts` table. */export default defineSeeder({after: ['users'],async run() {const author = await User.query().orderBy('id').firstOrFail()await Post.forceCreate({ title: 'Hello World', body: 'The first post.', status: 'published', author_id: author.id })await Post.forceCreate({ title: 'A draft', status: 'draft', author_id: author.id })},}) -
Run your migrations. In development,
migrateruns new seeders for you:Terminal window node strut migrateWhat you’ll see (something like this):
ran 2026_11_15_093000_create_posts_tableMigrations run (1 new, 5 total)✔ Seeded post.seeder.tsDatabase seeded
forceCreate() is for trusted code like seeders: it may set any real column, including ones that aren’t in the model’s fillable list (like author_id), but never Strutvane’s own columns such as id or created_at. Forms and the API use create(), which only accepts fillable columns. See Mass Assignment.
What run() receives
Section titled “What run() receives”run() gets one object with three helpers. You can ignore it, as above, and use your models directly.
| Name | What it is |
|---|---|
env |
The app’s typed environment (APP_ENV and the rest), for seeders that behave differently per environment |
db |
The database connection, for the rare raw SQL a seeder needs |
factory |
The factories |
import { defineSeeder } from '@strutvane/framework'import { Post } from '../../app/models/post.ts'
/** Lots of demo posts, but only on developers' machines. */export default defineSeeder({ after: ['users'], async run({ env }) { if (env.APP_ENV !== 'local') return await Post.factory().count(200).create() },})Creating a seeder for an existing table
Section titled “Creating a seeder for an existing table”For a table that already exists, or a seeder that isn’t about one table (for example “demo data”), use make:seeder:
node strut make:seeder PostSeeder # database/seeders/post.seeder.tsnode strut make:seeder DemoSeeder # database/seeders/demo.seeder.tsThe name ends in Seeder; the file name is the rest, in lower case with dashes, plus .seeder.ts (BlogPostSeeder → blog-post.seeder.ts). The new seeder is registered in database.seeder.ts like one from make:migration --seeder.
The order seeders run in
Section titled “The order seeders run in”database/seeders/database.seeder.ts is the main seeder: the one db:seed runs. It calls every other seeder, in order:
import { defineSeeder } from '@strutvane/framework'import RolesSeeder from './role.seeder.ts'import CategoriesSeeder from './category.seeder.ts'import UsersSeeder from './user.seeder.ts'import PostsSeeder from './post.seeder.ts'
/** Runs every seeder. The list between the markers is maintained by `node strut`. */export default defineSeeder({ async run({ call }) { // strut:seeders:start await call([RolesSeeder, CategoriesSeeder, UsersSeeder, PostsSeeder]) // strut:seeders:end },})call([...]) runs the seeders you pass, one after another. The list between // strut:seeders:start and // strut:seeders:end is maintained by the CLI: make:migration --seeder and make:seeder add each new seeder there (with its import), in the right place. Leave the markers in place. You may add your own code outside them, for example a seeder you only want in some environments:
async run({ call, env }) { // strut:seeders:start await call([RolesSeeder, CategoriesSeeder, UsersSeeder, PostsSeeder]) // strut:seeders:end if (env.APP_ENV === 'local') await call([DemoSeeder]) },The CLI orders the list from each seeder’s after: a seeder comes after the seeders of every table it names. So with these four seeders:
| File | after |
|---|---|
role.seeder.ts |
(none) |
user.seeder.ts |
['roles'] |
category.seeder.ts |
(none) |
post.seeder.ts |
['users', 'categories'] |
What you’ll see for node strut db:seed (something like this):
✔ Seeded role.seeder.ts ✔ Seeded category.seeder.ts ✔ Seeded user.seeder.ts ✔ Seeded post.seeder.tsDatabase seededSeeders with nothing in common keep file-name order, so the list is the same on every machine. Two seeders that wait for each other (a after b, b after a) are refused with the names of both, before anything runs.
When seeders run
Section titled “When seeders run”You rarely run seeders by hand, because node strut migrate does it for you:
| Situation | What happens |
|---|---|
| Development, a seeder that hasn’t run yet and isn’t empty | It runs once, as part of node strut migrate. |
| Development, a seeder that already ran | It’s skipped. Strutvane remembers it in a seeders table, so you never get duplicates. |
| You want it again, on purpose | node strut migrate --seed or node strut db:seed. |
Production (APP_ENV=production) |
Nothing is seeded, unless you pass --force. |
APP_ENV is production or staging and the seeder creates accounts |
Refused, always (see the first admin user). |
The seeders table is internal, like migrations: it never gets an API or a screen.
node strut migrate # migrate, then run seeders that haven't run yet (development)node strut db:seed # run every seeder againnode strut migrate --seed # migrate, then run the seeders againnode strut migrate:fresh --seed # start over: drop everything, migrate, seed (development only)Running one seeder: --class
Section titled “Running one seeder: --class”While you work on one seeder, run only that one:
node strut db:seed --class=PostSeederIt runs post.seeder.ts and nothing else, even if it already ran. The seeders in its after aren’t run for you, so their rows must already exist.
Seeding in production: --force
Section titled “Seeding in production: --force”Production data that every installation needs (a list of countries, your plans) can come from a seeder, run on purpose:
node strut db:seed --class=CountrySeeder --forceWithout --force, db:seed refuses in production. Seeders that create accounts are refused there even with --force. Write production seeders so they’re safe to run twice (see the advanced example below).
With Docker or without
Section titled “With Docker or without”The commands are the same. With Docker, node strut db:seed runs inside the app container, against the database container; you type it on your computer as usual. Without Docker, it runs on your computer against the database in .env (XAMPP, MAMP, Laragon, your own install; see Database: Getting Started). On Windows, macOS and Linux the commands are identical.
Three seeders, from small to advanced
Section titled “Three seeders, from small to advanced”Small: fixed starting data. A list your app needs to work, the same everywhere.
import { defineSeeder } from '@strutvane/framework'import { Category } from '../../app/models/category.ts'
export default defineSeeder({ async run() { for (const name of ['News', 'Guides', 'Releases']) { await Category.forceCreate({ name }) } },})What you’ll see: three rows in categories, with ids, slugs (if the table has one) and timestamps filled in.
Typical: data that depends on other rows. Look the parent up instead of guessing its id, and say you need it with after.
import { defineSeeder } from '@strutvane/framework'import { Post } from '../../app/models/post.ts'import { User } from '../../app/models/user.ts'
export default defineSeeder({ after: ['users'], async run() { const author = await User.query().where('email', 'admin@my-app.test').firstOrFail() await Post.forceCreate({ title: 'Welcome', body: 'Hello from the seeder.', status: 'published', author_id: author.id }) },})What you’ll see: one post by the admin. If the admin doesn’t exist, firstOrFail() stops the seeder with No row in "users" matching your query.
Advanced: safe to run twice, all or nothing. Production seeders (run with --force) should never create duplicates, and should never stop halfway:
import { defineSeeder, transaction } from '@strutvane/framework'import { Role } from '../../app/models/role.ts'
export default defineSeeder({ async run() { // A transaction: if one insert fails, none of them stay. await transaction(async () => { for (const name of ['admin', 'member', 'viewer']) { const exists = await Role.query().where('name', name).exists() if (!exists) await Role.forceCreate({ name }) } }) },})What you’ll see: the first run creates three roles; a second run changes nothing. See Transactions.
Seeding tables that belong to a team
Section titled “Seeding tables that belong to a team”If your app has teams (see Multi-tenancy), a team’s tables can only be written inside that team. Wrap the work in runWithTenant:
import { defineSeeder, runWithTenant } from '@strutvane/framework'import { Project } from '../../app/models/project.ts'import { Team } from '../../app/models/team.ts'
export default defineSeeder({ after: ['teams'], async run() { for (const team of await Team.all()) { await runWithTenant(team.id, async () => { await Project.forceCreate({ name: 'Getting started' }) }) } },})What you’ll see: one “Getting started” project per team, each with its team’s tenant_id filled in for you. Without runWithTenant, the ORM stops with tenant_required instead of guessing a team. Factories do this for you on tenant tables.
Fake data with factories
Section titled “Fake data with factories”A factory is a recipe for one realistic fake record. --seeder creates one next to your seeder:
import { defineFactory } from '@strutvane/framework'import { Post } from '../../app/models/post.ts'
export default defineFactory(Post, ({ faker, sequence }) => ({ title: `${faker.lorem.sentence()} (${sequence})`, body: faker.lorem.paragraph(), status: 'draft',}))Use it from a seeder:
import { defineSeeder } from '@strutvane/framework'import { Post } from '../../app/models/post.ts'import { User } from '../../app/models/user.ts'
export default defineSeeder({ after: ['users'], async run() { const users = await User.all() await Post.factory().count(10).create() // 10 saved posts await Post.factory().count(3).state({ status: 'published' }).create() // a state: override some values await Post.factory().count(5).for(users[0], 'author').create() // 5 posts by one user await Post.factory().count(20).recycle(users).create() // reuse existing users as authors },})- A state overrides some values (
{ status: 'published' }). - A sequence is the counter your definition receives (1, 2, 3…), so every record can differ.
for()attaches the records to an existing parent;has()creates children for each record.recycle()picks parents from a list you pass, instead of creating a new user for every post (a common reason demo databases fill up with thousands of users).
Factories write through forceCreate() (trusted code) and run inside the active team on tenant tables. Every option is on Factories.
The first admin user
Section titled “The first admin user”New apps come with a seeder that creates your roles and the first admin user. The installer runs it for you. With Docker or without, it’s the same seeder; with Docker it runs inside the app container.
- The admin’s email is in
.envasSEED_ADMIN_EMAIL(by defaultadmin@<your-app>.test). - The admin’s password is never written to any file: not to
.env, not to.env.example, not tostrutvane.json. The installer either generates one and shows it once in the terminal, or lets you type one (masked, at least 12 characters). It reaches the seeder only through an environment variable for that one run, and the account is marked “must change password at first sign-in”. - In CI, or when you missed the one-time password, set a new one:
node strut user:password admin@my-app.testThe admin seeder refuses to run when APP_ENV is production or staging, so it can never create a known account on a live server.
Common mistakes
Section titled “Common mistakes”mass_assignment in a seeder
Section titled “mass_assignment in a seeder”"author_id" can't be mass-assigned on "posts". If users may set it, add it to `fillable` in Model('posts', { fillable: [...] }). If your own code sets it, assign it directly (model.author_id = value) or use forceCreate().Why: create() only accepts fillable columns, even in a seeder.
Fix: seeders are trusted code, so use forceCreate() (factories already do):
await Post.forceCreate({ title: 'Hello', author_id: author.id })“Can’t tell which table … is about, so no seeder or factory was written”
Section titled ““Can’t tell which table … is about, so no seeder or factory was written”” ✖ Can't tell which table "backfill_slugs" is about, so no seeder or factory was written. → Name it create_<table>_table or add_<column>_to_<table>_table, or run make:migration again without --seeder/--factory.Why: --seeder needs to know the table, and only names like create_posts_table say which.
Fix: use a create_…_table or add_…_to_…_table name, or drop --seeder and use make:seeder instead.
“Refusing to seed with APP_ENV=production”
Section titled ““Refusing to seed with APP_ENV=production””Refusing to seed with APP_ENV=production: seeded accounts are for development only. Create a production admin with: node strut user:create --password-envWhy: seeding known or demo accounts on a live server is a security hole.
Fix: create real users with node strut user:create --password-env. For non-account data in production (a list of countries), run that one seeder with node strut db:seed --class=CountrySeeder --force, and make it safe to run twice.
“No row in “users” matching your query” from a seeder
Section titled ““No row in “users” matching your query” from a seeder”ModelNotFoundError: No row in "users" matching your query. It may not exist, may be soft-deleted, or may belong to another tenant.Why: the seeder ran before the seeder of the table it depends on, so the parent row isn’t there yet.
Fix: add the parent’s table to after (after: ['users']).
My seeder created the same rows twice
Section titled “My seeder created the same rows twice”Why: you ran it on purpose (db:seed or --seed) and it doesn’t check what’s already there.
Fix: make it safe to run twice (see the advanced example), or start over on your machine with node strut migrate:fresh --seed.
My new seeder never ran
Section titled “My new seeder never ran”Why: in development it already ran once (it’s remembered in the seeders table), or it was created by hand outside database/seeders/, or its file name doesn’t end in .seeder.ts.
Fix: run it again with node strut db:seed --class=PostSeeder; check the file is database/seeders/<name>.seeder.ts and default-exports defineSeeder({ … }).
tenant_required in a seeder
Section titled “tenant_required in a seeder”"projects" is tenant-scoped, but no tenant is active. Wrap the work in runWithTenant(tenantId, () => …) (the HTTP layer does this for you per request). Deliberate cross-tenant jobs use .unsafeWithoutTenancy(reason), which is audited.Why: a seeder runs outside any request, so no team is active.
Fix: wrap the writes in runWithTenant(team.id, …), as in Seeding tables that belong to a team.
Next steps
Section titled “Next steps”- Factories: states, sequences, relations and
recycle(). - Mass Assignment:
create()versusforceCreate(). - Migrations:
migrate --seed,migrate:fresh --seedand the other commands. - Database Testing: use seeders and factories to set up each test.