Seeds

Seeds populate your database with data using the full AppContext — collections, globals, services, and all infrastructure. Unlike migrations (which operate on raw SQL), seeds work through your application's typed API, ensuring data integrity and hook execution.

Defining a Seed

Place seed files in seeds/. Each file exports a seed definition using the seed() factory:

seeds/site-settings.seed.ts

import { seed } from "questpie/services";
export default seed({
	id: "siteSettings",
	description: "Default site settings",
	category: "required",
	async run({ globals, createContext, log }) {
		log("Seeding site settings...");

		const ctx = await createContext({ accessMode: "system", locale: "en" });
		await globals.siteSettings.update(
			{ shopName: "My Shop", tagline: "Welcome to our store" },
			ctx,
		);

		log("Site settings seeded");
	},
});

Seed Options

Option	Type	Description
`id`	`string`	Unique identifier for tracking execution
`description`	`string`	Human-readable description (shown in CLI output)
`category`	`SeedCategory`	When this seed should run
`run`	`(ctx) => Promise<void>`	Seed logic — populate data
`undo`	`(ctx) => Promise<void>`	Optional: remove seeded data
`dependsOn`	`string[]`	IDs of seeds that must run before this one

Category	Purpose	Runs In
`"required"`	System bootstrap (admin user, default roles, settings)	Every environment
`"dev"`	Development/demo data (sample content, test users)	Development only
`"test"`	Test fixtures (known datasets for integration tests)	Test suites only

Seed Context

The run and undo handlers receive a SeedContext — the full AppContext plus seed-specific helpers:

Property	Description
`collections`	Typed collection API (create, update, find, delete)
`globals`	Typed globals API
`db`	Raw database instance
`queue`	Publish background jobs
`email`	Send emails
`services`	User-defined services
`log`	Seed output logger (prints to CLI)
`createContext`	Create locale-specific contexts for multi-locale data

Multi-Locale Seeding

Use createContext to seed data in multiple locales:

seeds/site-settings.seed.ts

import { seed } from "questpie/services";
export default seed({
	id: "siteSettings",
	category: "required",
	async run({ globals, createContext, log }) {
		const ctxEn = await createContext({ accessMode: "system", locale: "en" });
		const ctxSk = await createContext({ accessMode: "system", locale: "sk" });

		await globals.siteSettings.update(
			{ shopName: "Sharp Cuts", tagline: "Precision grooming" },
			ctxEn,
		);
		await globals.siteSettings.update(
			{ tagline: "Precízna starostlivosť" },
			ctxSk,
		);

		log("Site settings seeded (EN + SK)");
	},
});

Idempotency

Seeds should be idempotent — safe to re-run without creating duplicates. Check for existing data before inserting:

seeds/demo-posts.seed.ts

import { seed } from "questpie/services";
export default seed({
	id: "demoPosts",
	description: "Demo blog posts",
	category: "dev",
	dependsOn: ["siteSettings"],
	async run({ collections, createContext, log }) {
		const ctx = await createContext({ accessMode: "system", locale: "en" });

		// Idempotency check
		const existing = await collections.posts.find(
			{ where: { slug: { eq: "hello-world" } }, limit: 1 },
			ctx,
		);
		if (existing.totalDocs > 0) {
			log("Demo posts already exist, skipping");
			return;
		}

		await collections.posts.create(
			{
				title: "Hello World",
				slug: "hello-world",
				content: "Welcome to our blog!",
				isPublished: true,
			},
			ctx,
		);
		log("Demo posts created");
	},
});

Dependencies

Use dependsOn to declare execution order. The seed runner resolves dependencies via topological sort:

export default seed({
	id: "demoData",
	category: "dev",
	dependsOn: ["siteSettings"], // Runs after siteSettings seed
	async run({ collections, createContext, log }) {
		// siteSettings is guaranteed to have run first
	},
});

Undo

Seeds can optionally define an undo function to remove seeded data:

export default seed({
	id: "demoData",
	category: "dev",
	async run({ collections, createContext, log }) {
		// ... create demo data
	},
	async undo({ collections, createContext, log }) {
		const ctx = await createContext({ accessMode: "system" });
		log("Cleaning demo data...");
		await collections.posts.delete({ where: {} }, ctx);
		await collections.services.delete({ where: {} }, ctx);
		log("Demo data cleaned");
	},
});

Running Seeds

CLI Commands

# Run all pending seeds (required category by default)
bunx questpie seed

# Run seeds of a specific category
bunx questpie seed --category dev

# Run a specific seed by ID
bunx questpie seed --only siteSettings

# Force re-run even if already executed
bunx questpie seed --force

# Dry-run: validate seeds without committing changes
bunx questpie seed --validate

Execution Tracking

Seeds are tracked in the database. Once a seed has been executed, it will not run again unless you use --force. This prevents duplicate data when re-running seeds.

The seed runner wraps each seed in a transaction. If a seed fails, its changes are rolled back and the seed is not marked as executed.

Jobs — Background tasks
Services — Reusable logic
CLI — All CLI commands
Codegen — How seeds are discovered