Seeding a demo environment#

Goal. Produce a database that tells a compelling story when someone opens the product. Not just rows — a believable narrative: customers with histories, orders with realistic timing, payments with a mix of outcomes.

Why Orchard. Hand-written SQL seed scripts rot. They drift from the schema, they can’t vary the story for different audiences, and they don’t compose. A scenario describes the story once; variables let you reshape it per demo.

Pattern: scenario per persona#

Define one scenario per demo persona. Each scenario composes the same components with different inputs.

scenarios/
├── demo_enterprise.hcl    # one merchant, high volume, low chargeback rate
├── demo_smb.hcl           # dozens of merchants, spiky data, typical chargebacks
└── demo_troubled.hcl      # one merchant, flagged transactions, support tickets

Example: enterprise demo#

scenario "demo_enterprise" {
  required_providers {
    postgres = { source = "builtin/postgres" }
  }

  variable "dsn" {}

  provider "postgres" {
    dsn = var.dsn
  }

  component "merchant" "acme" {
    source = "../components/merchant.hcl"
    inputs = {
      name           = "Acme Corporation"
      region         = "us"
      monthly_volume = 2500000
      verified       = true
    }
  }

  component "product_catalog" "acme_catalog" {
    source = "../components/product_catalog.hcl"
    inputs = {
      merchant_id = component.merchant.acme.id
      sku_count   = 120
    }
  }

  component "order_history" "last_quarter" {
    source = "../components/order_history.hcl"
    inputs = {
      merchant_id = component.merchant.acme.id
      days        = 90
      order_rate  = 45     # orders/day
      avg_amount  = 280.00
    }
  }

  output "merchant_id"   { value = component.merchant.acme.id }
  output "merchant_name" { value = component.merchant.acme.name }
}

The scenario reads like a description: “Acme Corp with a 120-SKU catalog and 90 days of order history.” The components underneath generate rows.

Running a demo setup#

orchard run scenarios/demo_enterprise.hcl \
  --var dsn="postgres://localhost/demo_db"

Before a demo, blow the database away and re-run. Orchard’s output printing gives you a URL or ID to log in with.

Tips#

Parameterize everything that might vary per audience: names, regions, dates, volume. Don’t hard-code “Acme Corp” inside a component.
Keep timing realistic. If your components generate timestamps, let scenarios control the time window — a “six months ago” demo looks different from a “yesterday” demo.
Avoid live external APIs. The HTTP provider is convenient for seeding integrations, but every external call makes your demo flakier. Mock or stub where you can.
Commit demo scenarios to your repo. They document what a representative customer looks like — useful far beyond sales.