@lunora/seed fills a Lunora database with realistic fake data derived from your defineSchema. It reads every table, maps each column to a generator (field-name aware: a string column named email becomes an email, firstName a first name), inserts foreign-key parents before their children, and lets you override any value.
Generated addresses always sit on the RFC 2606 reserved domain example.com, which accepts no mail — a seeded row can never turn into real email to a real stranger when a welcome job, a digest or an auth verification runs over it. Override the column when you need a domain of your own.
Generation is deterministic in seed alone for every column except the time-valued ones: a number column named like a timestamp (createdAt, expiresAt, …) is generated relative to the wall clock, so two runs with the same seed differ unless you also pin now (--now on the CLI). Ids are unaffected. Pin the (seed, now) pair and a plan is byte-identical across runs and machines. It is built on a vendored, input-hashed generator (a rebuilt copycat) over @faker-js/faker.
Install
pnpm add @lunora/seed@lunora/server, @lunora/testing, and @lunora/values are peer dependencies. A Lunora app already has @lunora/server and @lunora/values. Add @lunora/testing when you use the @lunora/seed/testing entry point.
Ways to seed
| You want to… | Use |
|---|---|
| Generate rows in memory, write them yourself | seedPlan (from @lunora/seed) |
Populate a lunoraTest harness | seed (from @lunora/seed/testing) |
| Author one table at a time, with types | createSeedClient (from @lunora/seed, or _generated/seed) |
| Seed a running dev worker | lunora seed (CLI) |
seedPlan — the pure core
seedPlan(schema, options) returns one TablePlan per seeded table ({ table, rows }), ordered so a table's FK parents come first. It performs no I/O: every adapter (test harness, CLI, client) builds on it.
import { seedPlan } from "@lunora/seed";
import schema from "./lunora/schema";
const plan = seedPlan(schema, {
counts: { posts: 30, users: 10 },
overrides: {
users: { email: (ctx) => `user${ctx.index}@example.com` },
},
seed: 1,
});
// plan === [{ rows: [...], table: "users" }, { rows: [...], table: "posts" }]
// Every post.authorId points at a generated user; each row carries an explicit `_id`.SeedOptions
Prop
Type
An override function receives an OverrideContext: { field, index, row, store, table }. row is the row built so far; store is a read-only view of every table's rows generated this run (use it to copy a value from the parent row a foreign key points at). Returning undefined defers to the generator, so a partial row that omits a field still gets a generated value.
seed — populate a test harness
@lunora/seed/testing runs seedPlan and inserts every row into a lunoraTest harness in FK order, preserving the planned _ids. It returns the inserted ids keyed by table, for assertions.
import { seed } from "@lunora/seed/testing";
import { lunoraTest } from "@lunora/testing";
import schema from "./lunora/schema";
const harness = lunoraTest(schema);
const ids = await seed(harness, schema, { counts: { posts: 20, users: 5 } });
expect(ids.users).toHaveLength(5);createSeedClient — typed, one table at a time
For a Snaplet-style DX, createSeedClient exposes each table as a method. Call it with a count, an inclusive range, explicit partial rows, or a count callback. Foreign keys connect to rows seeded earlier in the run, FK parents are seeded automatically, and state accumulates on $store / $ids (clear it with $reset()).
import { createSeedClient } from "@lunora/seed";
import schema from "./lunora/schema";
const seed = createSeedClient(schema, { seed: 1 });
const { users } = await seed.users(5);
const { posts } = await seed.posts((x) => x([10, 20])); // a deterministic count in [10, 20]
// Explicit partial rows — omitted columns are still generated:
await seed.users([{ name: "Alice" }, { email: "bob@example.com", name: "Bob" }]);
// Per-field overrides for one call:
await seed.posts(3, { overrides: { title: (ctx) => `Post ${ctx.index}` } });
seed.$ids.users; // every user id generated this run
seed.$reset(); // clear store/ids to drive a fresh runGenerated, project-bound client
When @lunora/seed is a declared dependency, codegen emits _generated/seed.ts, a createSeedClient with your schema and InsertModel already bound, so every table method is fully typed without passing a type argument.
import { createSeedClient } from "@/lunora/_generated/seed";
const seed = createSeedClient({ seed: 1 });
const { users } = await seed.users(5); // columns typed from InsertModelWithout codegen, pass the type yourself: createSeedClient<InsertModel>(schema).
SeedClientOptions
Prop
Type
Because every row carries an explicit _id, $ids is known whether or not you persist. A persist hook lets you write batches into the test harness or an admin import as they are generated.
lunora seed — seed a running worker
Generates from lunora/schema.ts and bulk-inserts through the worker's admin endpoint.
lunora seed # every table, default count (10)
lunora seed --table posts --count 100 # one table; FK parents seeded automatically
lunora seed --seed 42 --now 1750000000000 # byte-identical run (pin both)
lunora seed --dry-run # print the NDJSON, insert nothing
lunora seed --reset # wipe local .wrangler/state first (local dev only)Other flags: --allow-orphans (let a required foreign key with no parent row take a dangling id instead of failing), --batch-size (rows per HTTP request, default 500), --url (worker URL, default http://localhost:8787), --prod (requires an explicit --url), --token / LUNORA_ADMIN_TOKEN (admin bearer; prefer the env var), --yes (skip the non-local confirmation prompt).
--reset clears local .wrangler/state only; it cannot be combined with --prod or a remote --url.Limitations
.unique()columns are dealt distinct values by construction. Each value is a function of the row's absolute index, not a hash of the row, so two rows in the same run never collide — including across the several callsindexOffsetexists to support. A.unique()foreign key (v.id("users").unique(), the way to spell a 1:1) is dealt from its parent pool without replacement, so the pool's size is its domain; across calls that holds only while the parent pool is unchanged. A column whose domain is too small to cover the requested count (a boolean, a three-literalv.union(), a parent table with fewer rows than the child) is refused at plan time, with the column named, before anything is inserted.- Table-level unique indexes are dealt too. A single-column
uniqueindex counts as.unique()on that column, with one exception: a.url()column is generated, and a value an earlier row of the same call already took is redrawn up to 8 times before the plan refuses. Distinctness for those columns holds only within one call, so a latercreateSeedClientcall can repeat a value. An explicit.unique()on such a column is still refused. A multi-column one is dealt from the members whose number of distinct values is known: foreign keys first, then closed domains (enum, boolean, literal union, bounded number), then, only when those cannot cover the row count, members whose value can carry an index (a plain string takes a tag, an unbounded number a counter). The rest keep their generated values, so a through table over two foreign keys of N and M parents seeds up to N × M distinct pairs and refuses more, with the index named, while a.url()column beside a foreign key is left as generated. A member with no known count (an array of an open element type, object, record, storage id, open union or.url()string) never counts towards the index, but it keeps its per-row generated value, so an index holding one is not refused for being short of counted combinations. Two limits: the pairs are distinct within one call, but successivecreateSeedClientcalls can repeat a pair once a parent table has grown between them, or once their running total first needs a tagged or counted member; and an index with a member that is server-filled or a self-reference is left to the generator. An overridden member keeps its deal: an override that returnsundefinedfor a row defers to the dealt value, and the index's capacity is still checked, where a single overridden column is not. An index that shares a column with an earlier one is still checked, but counts only the earlier index's leading columns it contains and the members it deals itself, so overlapping indexes can be refused sooner than either alone. An array over a finite element domain (v.array(v.boolean()).max(2)) is counted and dealt by length and element, so an array capped at zero items is one value, not many, and only the arrays the column's own validator accepts are dealt (a nullable column addsnullas one more value); - A foreign key never dangles silently. A required foreign key with no row to point at (an empty parent, or the first row of a required self-reference in an empty table) is refused with the column named. An optional one is left out and a nullable one is
null. PassallowOrphans: true(--allow-orphans) to accept a placeholder id instead. A foreign-key cycle across tables is resolved by assigning each cycle parent's ids before its rows are generated, so every cell points at a real row whichever table is declared first. - A column the generator cannot satisfy is refused, not guessed at.
v.from(externalSchema), a.pattern()column, and anyformatwith no generator behind it (onlyemailandurihave one) fail at plan time with the column named, rather than seeding a value the column's own validator rejects on insert. Supply those throughoverrides, or skip the table withonly. - Seeding is deterministic by design. Re-running with the same
seedregenerates identical_ids, which the import path skips as conflicts. Use a differentseedfor fresh rows, or--resetto wipe local state first.
Related
@lunora/server: defines thedefineSchemathat seeding introspects.@lunora/testing: the in-memory harness@lunora/seed/testingseeds.@lunora/cli: ships thelunora seedcommand.