You need: a project with tables. There is no separate fixture format to learn.
The mental model
pithy seed is the command, the data layer is where a fixture’s schema comes from, and live fixtures is the variant that talks to a real account.
A seed set is the direct analog of a migration. A migration describes schema changes; a seed set describes rows, entries and assets.
Both are namespaced per capability, ordered, composed library-before-app into one registry, and run by one command against a named environment.
Authoring one
import { defineSeed, d1SeedGroup } from "@pithy-sh/core/src/seed/seed";
import { BoardEntry } from "./data/entry";
export const demoBoardSeed = defineSeed({
name: "demo_board",
order: 1,
environments: ["dev", "staging"],
d1: [
d1SeedGroup("app", "boardEntries", BoardEntry, [
{ id: "demo-1", boardId: "weekly", userId: "demo-user-1", score: 4200, createdAt: new Date() },
{ id: "demo-2", boardId: "weekly", userId: "demo-user-2", score: 3100, createdAt: new Date() },
]),
],
});Four things there are worth noticing.
Rows are app-shape values. That date is a real Date, not an epoch number — the same shape your application code produces.
The schema binds the row type at compile time and is not stored. The write path resolves the live schema itself from the composed registry, so a fixture can never drift from the real table shape.
order composes exactly like a migration’s, libraries before the app, ties broken on the namespaced key.
environments is an allowlist. This set is only ever composed into a run targeting one of those. Listing production is the only way a set ever reaches production — there is no default-on environment.
Contribute it on your capability’s seeds, beside its databases and migrations.
Validation, then insertion
Every row is validated before anything is written — through the exact inverse of the parse your application reads with. A single bad fixture fails its whole group with a field-level error, and nothing for that group lands.
Then the write is deliberately boring:
- D1 rows insert ignoring conflicts
- KV entries write by key, which is naturally idempotent
- Nothing is ever updated or deleted
Which is why seeding is safe to run repeatedly, and safe as a step in a pipeline that provisions an ephemeral environment.
It is also why editing a fixture and re-running does nothing. The row already exists, so it is left alone.
--redo, and what it actually costs
pithy seed --env dev --redoNot a per-row refresh. A full schema reset: every migration rolled back, every one reapplied, then a normal seed.
Because every table comes back empty, the ordinary non-destructive writes just work — there is nothing left to special-case.
And nothing left of what was there. It destroys every row in every table the registry owns, not just the rows a fixture wrote. Data you inserted by hand does not survive.
Its gate is stricter than the seed gate
--yes means yes, this is not dev, and it was designed to authorize writing seed rows, which is additive and harmless. A reset drops every table first.
Letting one flag authorize both would mean a script that knew only to pass --yes could destroy an environment’s entire dataset.
| Environment | Plain seed | --redo |
|---|---|---|
dev | Free | Free |
| Anything else | --yes | The exact phrase, naming that environment |
| Production | --yes plus the seed phrase | The reset phrase, refused headlessly without it |
The phrase names its environment, so one typed for staging cannot be pasted into a command targeting another.
A non-dev reset is audited at critical severity, truthfully — recorded as a failure, with the command still failing, if it dies partway.
Fixture size
Make a fixture as big as the thing it has to prove. A paged list needs more rows than a page.
D1 accepts 100 bound parameters per statement, and an insert binds one per column per row — so a seven-column table fits about fifteen rows. Each group is chunked from that table’s own column count, so the limit is never a fixture’s problem and never a number to look up.
A group is not atomic across chunks, and ignoring conflicts is what makes that safe: a run that dies partway is re-run, landed rows are ignored, and the rest go in.
Media fixtures
Some fixtures need real bytes — an avatar, a demo thumbnail — uploaded to a real store rather than just a row.
once uploads on its first run and skips forever after, writing the store’s minted id back so the row and the asset stay paired. always re-uploads.
Every asset a fixture creates is stamped with the project and environment, because those stores key by an id they mint rather than by a name you choose — so there is nowhere to put a project segment, and metadata is the only attribution available.
Minting a dev session
The one fixture you will use daily. Seeding mints a real, signed-in session for every user it creates, so you can be any of them under pithy dev rather than round-tripping a magic link. Press l and pick who.
Opt in per machine, never per repo — the user key in dev.json, in the config directory, names who is offered first. The file alone mints nothing. No key, no session.
The set is dev-only, so it can never compose into staging or production.
Dev secrets can never reach a managed environment
Not by flag, not by argument. Seeding production seeds none of them and says so.
The refusal is structural — no signature in that path accepts a managed environment — because seeding that file into production would rotate every secret at once, with no undo.
A feature is a managed environment here too. A branch’s secrets exist only in its own Secrets Store and SECRETS database, which pithy provision --feature writes and nothing reads back, so a set that asks context.secret for one on a feature is refused exactly as it is on staging and prod. The dev secrets file is never opened for anything but dev.
Sealing a fixture under a secret this run just minted
Some fixtures have to seal at creation time. A row holding a private key encrypted under the environment’s key-encryption secret can only be built while that secret is in hand — and for a Secrets Store secret there is exactly one moment when it is.
pithy provision creates a random value for every store secret the registry declares mintable, writes it into the account’s Secrets Store, and lets it go. Nothing reads an entry back: the store is write-only from the CLI. Provisioning then migrates and seeds in the same process, so the stretch between that write and the seed is the only time the value exists anywhere the toolchain can see it. After the run, it is unrecoverable by design.
prepare: async (context) => {
const key = context.mintedThisRun("connection-key");
if (!key) return {}; // nothing was minted this run
return { d1: [d1SeedGroup("app", "connections", Connection, [sealUnder(key)])] };
},- It is not
context.secret, and the two are not interchangeable.secretanswers what the environment holds and refuses outsidedev, absolutely.mintedThisRunanswers the strictly narrower did this run create one, a moment ago, in memory. A set asking here for a secret this run did not mint getsundefinedwherever it runs,devincluded. - Synchronous, because it cannot fetch. There is no file to open and no request to make.
- Empty is ordinary, and never an error. A re-run mints nothing — absence is checked before anything is generated — so every name answers
undefined. A set that needs a minted value and is handed none says so itself; nothing is invented on its behalf. - Which runs can offer it.
pithy provision --feature, which always seeds, andpithy provision --env <environment> --seed. Those are the only commands that mint and seed in one process. A standalonepithy seed, in any environment, mints nothing and offers an empty channel — so a set that seals must be run through provisioning, and a set that must work under both handlesundefined. - No minted value reaches any output. Not a log line, not a report, not
--json, not an artifact, not an error message. What a run says is that a secret was minted, and which entry it went to.
Where this Worker answers: context.origin
A prepared set can ask where the Worker it is being written through is reachable — useful for a row that has to hold a callback URL.
- It is an address, not an identity. Never build a stored, later-verified value from it — an issuer, an audience, a signing scope — because the same project answers on a different port in every checkout and a different origin in every environment.
- Off
dev, it is the Worker’s own address. A declared environment’s comes from its config — thedomainsdeclaration, the route,vars.BASE_URL, aspithy envresolves it. A feature’s ishttps://<script>.<subdomain>.workers.dev, derived from the feature Worker’s script name and the account’sworkers.devsubdomain.pithy seed --host <host>overrides either. nullis an answer, never a guess. A clone that has run neitherpithy setupnorpithy dev, so nothing has pinned its ports, a Worker added after the block was pinned, or a deployed Worker with no address at all. A set that cannot work without an origin refuses and says so, with a validation error rather than a bare one, so the CLI renders a problem line and an action rather than a stack. An invented origin would be indistinguishable from a real one.
Check it worked
- A run reports one line per set, and a set the environment disallows is reported rather than silently dropped
- Running twice writes nothing the second time, and each line says its rows are already there
- A bad fixture fails its group with a field-level error
--dry-runprints the plan and touches nothing- Pressing
lunderpithy devopens a signed-in browser