How to Seed CockroachDB with Realistic Test Data

The Problem

CockroachDB gives you distributed SQL with horizontal scalability and strong consistency. But testing distributed behavior requires realistic data volumes. Three rows in your users table will not reveal issues with range splits, query distribution, or multi-region latency. You need hundreds or thousands of records with realistic distributions across your schema.

CockroachDB is wire-compatible with PostgreSQL, so most Postgres tools work. But building seed scripts that generate enough realistic data with proper foreign key relationships is still a manual chore. Faker.js helps with field values, but you handle the relational wiring yourself.

The Solution: MockHero API

MockHero generates relationally-consistent data that you can insert directly into CockroachDB using any Postgres-compatible driver. Define your tables with ref fields, request JSON or SQL, and seed your cluster in seconds. Because CockroachDB uses the Postgres wire protocol, the seed script is nearly identical to a standard Postgres seeding workflow.

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": "regions",
      "count": 5,
      "fields": [
        { "name": "id", "type": "uuid" },
        { "name": "name", "type": "enum", "params": { "values": ["us-east","us-west","eu-west","ap-south","ap-east"] } },
        { "name": "active", "type": "boolean" }
      ]
    },
    {
      "name": "warehouses",
      "count": 20,
      "fields": [
        { "name": "id", "type": "uuid" },
        { "name": "region_id", "type": "ref", "params": { "ref": "regions.id" } },
        { "name": "name", "type": "company_name" },
        { "name": "address", "type": "street_address" },
        { "name": "capacity", "type": "integer", "params": { "min": 1000, "max": 50000 } }
      ]
    },
    {
      "name": "inventory_items",
      "count": 200,
      "fields": [
        { "name": "id", "type": "uuid" },
        { "name": "warehouse_id", "type": "ref", "params": { "ref": "warehouses.id" } },
        { "name": "sku", "type": "uuid" },
        { "name": "product_name", "type": "product_name" },
        { "name": "quantity", "type": "integer", "params": { "min": 0, "max": 500 } }
      ]
    }
  ],
  "format": "json"
}'

Step-by-Step Guide

1. Install dependencies

npm install pg

2. Get your MockHero API key

Sign up at mockhero.dev/sign-up and copy your API key.

3. Write the seed script

Create seed.mjs:

import pg from "pg";
const { Client } = pg;

const client = new Client({ connectionString: process.env.COCKROACH_URL });
await client.connect();

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: "regions",
        count: 5,
        fields: [
          { name: "id", type: "uuid" },
          { name: "name", type: "enum", params: { values: ["us-east","us-west","eu-west","ap-south","ap-east"] } },
          { name: "active", type: "boolean" },
        ],
      },
      {
        name: "warehouses",
        count: 20,
        fields: [
          { name: "id", type: "uuid" },
          { name: "region_id", type: "ref", params: { ref: "regions.id" } },
          { name: "name", type: "company_name" },
          { name: "address", type: "street_address" },
          { name: "capacity", type: "integer", params: { min: 1000, max: 50000 } },
        ],
      },
      {
        name: "inventory_items",
        count: 200,
        fields: [
          { name: "id", type: "uuid" },
          { name: "warehouse_id", type: "ref", params: { ref: "warehouses.id" } },
          { name: "sku", type: "uuid" },
          { name: "product_name", type: "product_name" },
          { name: "quantity", type: "integer", params: { min: 0, max: 500 } },
        ],
      },
    ],
    format: "json",
  }),
});

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

for (const r of data.regions) {
  await client.query(
    "INSERT INTO regions (id, name, active) VALUES ($1, $2, $3)",
    [r.id, r.name, r.active]
  );
}
for (const w of data.warehouses) {
  await client.query(
    "INSERT INTO warehouses (id, region_id, name, address, capacity) VALUES ($1, $2, $3, $4, $5)",
    [w.id, w.region_id, w.name, w.address, w.capacity]
  );
}
for (const item of data.inventory_items) {
  await client.query(
    "INSERT INTO inventory_items (id, warehouse_id, sku, product_name, quantity) VALUES ($1, $2, $3, $4, $5)",
    [item.id, item.warehouse_id, item.sku, item.product_name, item.quantity]
  );
}

console.log(
  "Seeded", data.regions.length, "regions,",
  data.warehouses.length, "warehouses, and",
  data.inventory_items.length, "inventory items"
);
await client.end();

4. Run the script

node seed.mjs

5. Verify in the CockroachDB SQL shell

cockroach sql --url "$COCKROACH_URL" -e "SELECT w.name, r.name AS region FROM warehouses w JOIN regions r ON w.region_id = r.id LIMIT 10;"

Why MockHero vs Faker / Manual Seeds

• Distributed-ready volumes — easily generate hundreds or thousands of rows to test range splits and multi-node behavior.
• Postgres-compatible — CockroachDB uses the Postgres wire protocol, so MockHero's output works with any pg driver.
• Multi-table relationships — regions, warehouses, and inventory items are all linked automatically via ref fields.

Get Started

Seed your CockroachDB cluster with production-realistic data. Sign up free at mockhero.dev and get 1,000 rows per month, no credit card required.