How to Seed a Neon Database with Test Data

The Problem

Neon gives you serverless Postgres with branching, but every new branch starts empty. If you are building a feature that depends on realistic data, you have to either copy production (risky and slow) or write INSERT statements by hand. Neither approach scales when you need fresh data for each branch.

Faker libraries help, but they dump the relationship problem on you. You still have to generate users first, collect their IDs, then reference them when creating orders. One mistake and your foreign keys break.

The Solution: MockHero API

MockHero generates realistic, relationally-consistent test data in a single HTTP call. Define tables with 156+ field types, link them with ref fields, and get back JSON or SQL ready for Neon. No dependencies, no ORM required.

Quick Setup

curl -X POST https://api.mockhero.dev/api/v1/generate \
  -H "x-api-key: mh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "tables": [
    {
      "name": "customers",
      "count": 15,
      "fields": [
        { "name": "id", "type": "uuid" },
        { "name": "name", "type": "full_name" },
        { "name": "email", "type": "email" },
        { "name": "company", "type": "company_name" }
      ]
    },
    {
      "name": "invoices",
      "count": 40,
      "fields": [
        { "name": "id", "type": "uuid" },
        { "name": "customer_id", "type": "ref", "params": { "ref": "customers.id" } },
        { "name": "amount_cents", "type": "integer", "params": { "min": 1000, "max": 500000 } },
        { "name": "status", "type": "enum", "params": { "values": ["draft","sent","paid","overdue"] } },
        { "name": "issued_at", "type": "datetime" }
      ]
    }
  ],
  "format": "sql"
}'

Step-by-Step Guide

1. Install dependencies

npm install @neondatabase/serverless

2. Get your MockHero API key

Sign up at mockhero.dev/sign-up and grab your key from the dashboard.

3. Write the seed script

Create seed.mjs:

import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL);

const res = await fetch("https://api.mockhero.dev/api/v1/generate", {
  method: "POST",
  headers: {
    "x-api-key": process.env.MOCKHERO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tables: [
      {
        name: "customers",
        count: 15,
        fields: [
          { name: "id", type: "uuid" },
          { name: "name", type: "full_name" },
          { name: "email", type: "email" },
          { name: "company", type: "company_name" },
        ],
      },
      {
        name: "invoices",
        count: 40,
        fields: [
          { name: "id", type: "uuid" },
          { name: "customer_id", type: "ref", params: { ref: "customers.id" } },
          { name: "amount_cents", type: "integer", params: { min: 1000, max: 500000 } },
          { name: "status", type: "enum", params: { values: ["draft","sent","paid","overdue"] } },
          { name: "issued_at", type: "datetime" },
        ],
      },
    ],
    format: "json",
  }),
});

const { data } = await res.json();

for (const c of data.customers) {
  await sql(
    "INSERT INTO customers (id, name, email, company) VALUES ($1, $2, $3, $4)",
    [c.id, c.name, c.email, c.company]
  );
}

for (const inv of data.invoices) {
  await sql(
    "INSERT INTO invoices (id, customer_id, amount_cents, status, issued_at) VALUES ($1, $2, $3, $4, $5)",
    [inv.id, inv.customer_id, inv.amount_cents, inv.status, inv.issued_at]
  );
}

console.log(
  "Seeded", data.customers.length, "customers and",
  data.invoices.length, "invoices"
);

4. Run it

node seed.mjs

5. Verify in the Neon console

Open the SQL Editor in your Neon dashboard and run SELECT * FROM invoices LIMIT 5; to confirm the data landed correctly with valid foreign keys.

Complete Example

The script above seeds customers and invoices with proper foreign key references. For even simpler seeding, request "format": "sql" from MockHero and pipe the output directly into psql.

Why MockHero vs Faker / Manual Seeds

• Branch-friendly — run the script against any Neon branch for instant realistic data.
• SQL output mode — get raw INSERT statements you can run directly, no driver needed.
• 156+ field types — from iban to avatar_url, data looks production-real.

Get Started

MockHero has a free tier with 1,000 rows/month. No credit card needed. Sign up now and seed your next Neon branch in seconds.