Seed demo data and make preview databases

Seed the same synthetic demo rows every time, and give each git branch a preview database that expires after its time to live.

Planned for 0.4

Status Status is where the work is: Planned (in a milestone, not started), Building (tickets in progress), Preview (usable, may change), then the stability it ships at.

Stability The promise an interface ships with.

Stable Follows semantic versioning; breaking changes need a new major, 12 months of overlap and a codemod.
Beta Usable in production; may change before it becomes stable.
Experimental May change or go away; needs an explicit opt-in in main.yaml.

Stability levels

View as Markdown Open in Claude Edit

Updated 2026-10-28

You want realistic demo data on your laptop and in preview environments, with no real personal data in it. This guide seeds a database from a number, gives each git branch its own preview database, and removes old previews. It takes about 20 minutes.

Planned for 0.4 (spec seed-preview).

You need

A MainSDK app with db models.
A database that can be seeded: a local one, or a preview database. Production is refused.

1. Describe the demo data

main.yaml

seed:
  number: 42                    # the same number gives the same rows
  tenants: 3
  regions: [eu, in, us]
  per-tenant: { users: 20 }
  models:
    orders:
      count: 50
      fields:
        status: [paid, shipped, refunded]
        note: { text: short }
preview:
  driver: local                 # neon | supabase | local
  from: main
  seed: true
  ttl: 7d

Use reserved values for anything that looks like a person. An email must use a reserved domain, such as example.com, or MAIN-SEED-0011 fails the check.

2. Seed a local database

bash

npx mainsdk seed --number 42 --tenants 3

The command prints a digest. The same number, schema and SDK major always give the same digest. Use --reset to clear the seeded rows first.

3. Create a preview for the branch

bash

npx mainsdk preview up

The preview is named after the current git branch and is seeded with the same number. Running preview up again on the same branch returns the same preview.

4. Clean up

bash

npx mainsdk preview list
npx mainsdk preview prune

prune deletes previews whose branch is gone or whose ttl has passed. It never deletes the parent database.

Check it worked

mainsdk seed prints a digest, and running it twice with --reset prints the same digest.
mainsdk preview up prints the preview's name and its database secret reference.

If it fails

MAIN-SEED-0001: the environment is production. Seed a local or preview environment.
MAIN-SEED-0002: the target database is not seedable. Point at a local or preview database.
MAIN-PREVIEW-0001: the db driver cannot branch. Use preview.driver: local.
MAIN-PREVIEW-0002: the provider failed while making the preview. Check its status and credentials, then run preview up again.

Prompt for your coding agent

Seed this app with the same demo data every time, using MainSDK's seed and preview interface. Use reserved example emails only, give each git branch a preview database that expires after seven days, and make preview prune part of the nightly job.

Was this page helpful?