Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Seeding

View as Markdownllms.txt

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.

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
  1. Ask for a seeder when you create the table:

    Terminal window
    node strut make:migration create_posts_table --seeder

    What you’ll see (something like this; the exact wording isn’t final):

    Created database/migrations/2026_11_15_093000_create_posts_table.ts
    Created app/models/post.ts
    Created database/seeders/post.seeder.ts
    Created database/factories/post.factory.ts
    Next: add your columns to the migration, then run `node strut migrate`.

    --seeder also creates the factory, because seeders usually use one, and registers the seeder in database/seeders/database.seeder.ts.

  2. 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()
    },
    })

    after lists the tables whose seeders must run first. Strutvane fills it in from your migration’s foreign keys (posts.author_id points at users).

  3. 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 })
    },
    })
  4. Run your migrations. In development, migrate runs new seeders for you:

    Terminal window
    node strut migrate

    What you’ll see (something like this):

    ran 2026_11_15_093000_create_posts_table
    Migrations run (1 new, 5 total)
    ✔ Seeded post.seeder.ts
    Database 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.

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
database/seeders/demo.seeder.ts
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()
},
})

For a table that already exists, or a seeder that isn’t about one table (for example “demo data”), use make:seeder:

Terminal window
node strut make:seeder PostSeeder # database/seeders/post.seeder.ts
node strut make:seeder DemoSeeder # database/seeders/demo.seeder.ts

The 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.

database/seeders/database.seeder.ts is the main seeder: the one db:seed runs. It calls every other seeder, in order:

database/seeders/database.seeder.ts
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:

database/seeders/database.seeder.ts (excerpt)
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.ts
Database seeded

Seeders 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.

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.

Terminal window
node strut migrate # migrate, then run seeders that haven't run yet (development)
node strut db:seed # run every seeder again
node strut migrate --seed # migrate, then run the seeders again
node strut migrate:fresh --seed # start over: drop everything, migrate, seed (development only)

While you work on one seeder, run only that one:

Terminal window
node strut db:seed --class=PostSeeder

It 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.

Production data that every installation needs (a list of countries, your plans) can come from a seeder, run on purpose:

Terminal window
node strut db:seed --class=CountrySeeder --force

Without --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).

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.

Small: fixed starting data. A list your app needs to work, the same everywhere.

database/seeders/category.seeder.ts
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.

database/seeders/post.seeder.ts
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:

database/seeders/role.seeder.ts
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.

If your app has teams (see Multi-tenancy), a team’s tables can only be written inside that team. Wrap the work in runWithTenant:

database/seeders/project.seeder.ts
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.

A factory is a recipe for one realistic fake record. --seeder creates one next to your seeder:

database/factories/post.factory.ts
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:

database/seeders/post.seeder.ts (with factories)
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.

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 .env as SEED_ADMIN_EMAIL (by default admin@<your-app>.test).
  • The admin’s password is never written to any file: not to .env, not to .env.example, not to strutvane.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:
Terminal window
node strut user:password admin@my-app.test

The admin seeder refuses to run when APP_ENV is production or staging, so it can never create a known account on a live server.

"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-env

Why: 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']).

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.

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({ … }).

"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.