new in 0.1.8 TUI · Web Studio · Regenerate Same engine, three surfaces. Plus PK-stable re-rolls without re-running the whole schema. see what shipped →

● seed data, grown from your schema

Seed data that
actually fits your schema.

Point at a database or a schema file. Get realistic, constraint-aware rows. Offline, deterministic, no API key.

$ pip install dbsprout

get started →

· Python 3.10+ · MIT · 3,600+ tests · 100% FK integrity · 95%+ coverage

· authors 3 cols 0 fk

▸ books 4 cols 1 fk

· categories 3 cols 1 fk

· orders 4 cols 1 fk

· order_items 4 cols 2 fk

§00

● Three surfaces. One engine.

Run it however you work.

The CLI is still the default. v0.1.8 adds a Terminal UI for live exploration and a Web Studio for review and handoff. The generation engine is identical — same specs, same determinism, same MIT.

● CLI since v0.1.0

Scriptable.

The original surface. Pipe-friendly. Lives in CI and in your shell history.

$ dbsprout generate --rows 1000


Generating  ████████████████████ 100%
Tables 5/5  · rows 250  · 0.042s
✓ fk_satisfaction · pk_uniqueness · unique

● TUI new in v0.1.8

Interactive.

Schema browser, per-table progress, live quality panel. Works over SSH.

$ dbsprout tui


┌─ Schema ──────┬─ Progress ───────┐
│ ▸ authors   3 │ books   █████ 100│
│   books     4 │ orders  ███░░  60│
│   orders    4 │ items   ░░░░░   0│
└───────────────┴──────────────────┘
  [q] quit  [⏎] inspect

● Web Studio new in v0.1.8

Reviewable.

FastAPI dashboard with ERD, spec grid, SSE progress, fidelity + detection report.

$ dbsprout serve --port 8420

§01

● See it work

Schema in. Seed SQL out.

dbsprout reads your real schema and grows rows that fit it — referential integrity included.

-- schema.sql  (input)
CREATE TABLE authors (
  id      INTEGER PRIMARY KEY,
  name    TEXT NOT NULL,
  country TEXT
);

CREATE TABLE books (
  id           INTEGER PRIMARY KEY,
  author_id    INTEGER NOT NULL REFERENCES authors(id),
  title        TEXT NOT NULL,
  price        NUMERIC(6,2),
  published_on DATE
);

dbsprout generate →

-- seeds/002_books.sql  (generated)
INSERT INTO books (id, author_id, title, price, published_on) VALUES
  (1, 3, 'The Salt Graves',  14.99, '2021-06-02'),
  (2, 1, 'Northwind',          9.50, '2019-11-15'),
  (3, 3, 'A Lantern Year',   22.00, '2023-02-28'),
  (4, 2, 'Ledger of Tides',  18.75, '2024-04-09'),
  (5, 1, 'Quiet Apparatus',  11.25, '2022-09-21');

-- author_id values sampled from real authors PKs

§02

● Why DBSprout

Fake seed data lies. This doesn't.

lorem ipsum users. Impossible foreign keys. Distributions nothing like production. Fixtures that rot the moment the schema changes. dbsprout reads your real schema and grows data that fits it.

● Schema-first 01

Read the real schema.

No config to start. Point at a live database — SQLite, Postgres, MySQL, SQL Server — or a schema file: SQL DDL, DBML, Mermaid, PlantUML, Prisma.

$ dbsprout init --db postgresql://localhost/myapp

● 100% FK integrity 02

Foreign keys that resolve.

Tables are topologically ordered, FK columns sample from real parent keys, cycles and self-references are resolved automatically. Validation has to pass before output ships.

$ dbsprout validate

● Deterministic · Offline 03

Same seed, same rows. Always.

The same --seed (default 42) produces identical output across machines. No internet, API key, or account required. Embed it in CI without secrets.

$ dbsprout generate --seed 42

§03

● Pick an engine

Four ways to grow.

Start with heuristic — fast, no model required. Bring an LLM when you need column-aware accuracy. Same CLI, swap the flag.

┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Engine      ┃ Speed                  ┃ Quality                ┃ Use when                             ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ heuristic   │ 100K+ rows / sec       │ ~80% semantic          │ Default. Fast fixtures, no model.    │
│ spec        │ cached after first run │ high semantic          │ Column-aware accuracy via LLM.       │
│ statistical │ fast                   │ distribution-faithful  │ You have a real data sample.         │
│ finetuned   │ cached                 │ highest                │ You trained a LoRA adapter.          │
└─────────────┴────────────────────────┴────────────────────────┴──────────────────────────────────────┘

§04

● Solve a specific problem

Recipes.

Task-oriented how-tos for the situations you actually hit. See all recipes →

01 · recipe

Seed CI test fixtures

Deterministic, fast, reproducible. Drop dbsprout generate into your pipeline.

↗

02 · recipe

Re-seed after a migration

Diff the schema, update only what changed. Old rows stay stable.

↗

03 · recipe

Match production distributions

Fit a statistical model to a real sample. No PII in your fixtures.

↗

04 · recipe

Bulk-load millions of rows

Native COPY / LOAD DATA throughput. Stream directly into the engine.

↗

§05

● Drop it in

Works with what you already use.

Four live databases. Five schema-file formats. Same two commands.

dbsprout init --db postgresql://user:pass@localhost:5432/mydb
dbsprout generate --rows 500 --dialect postgresql

.sql

SQL DDL

Auto-detects dialect via sqlglot

.dbml

DBML

Full DBML spec via pydbml

.mmd

Mermaid

erDiagram blocks with relationships

.puml

PlantUML

entity blocks with FK arrows

.prisma

Prisma

Model definitions via DMMF

—

Live DB

SQLite, Postgres, MySQL, SQL Server

§06

● Frequently asked

The honest questions.

01 Is my schema or data sent anywhere?

No. The default engine is fully offline. Even with --engine spec, only column names and types are shown to the LLM — and you can pin it to a local model (Qwen 2.5-1.5B embedded, or your own Ollama). Cloud LLMs require explicit --privacy cloud.

02 Does it actually understand my columns?

03 What about CHECK constraints and uniqueness?

04 How does it handle FK cycles?

05 How big can I go?

06 Why not just use Faker?

Stop seeding lies.

Install once. Init once. Generate forever — deterministically.