Documentation

How It Works

Seedfast connects to your database, reads its schema, generates realistic data, and writes it directly back — in a single operation. There's nothing to copy, configure, or export.

Schema-driven generation#

When you run seedfast seed, the first thing Seedfast does is read your schema:

Table and column names
Data types and constraints
Foreign key relationships
Check constraints and enum values

This is the only input Seedfast needs to generate data. It doesn't require a configuration file, a separate schema definition, or any manual setup. You connect a database and it works with what's there.

The schema analysis happens server-side. Your credentials stay local — only metadata (table names, column types, constraints) is transmitted. Your actual data is never sent anywhere.

Direct to your database#

Seedfast writes data directly into your database tables. There are no intermediate steps:

No CSV exports to import later
No SQL files to run manually
No browser downloads or dashboard interactions

You run seedfast seed, data appears in your tables. This works identically for local databases and remote ones — the same command, the same workflow.

# Local database
seedfast seed --scope "50 users with orders"

# Remote database — same command, different connection
seedfast connect postgres://user:pass@remote-host:5432/db
seedfast seed --scope "50 users with orders"

The generation pipeline#

Once the schema is read, Seedfast runs through a planning phase before writing anything:

Domain inference — analyzes table and column names to understand what the data represents
Dependency resolution — determines the correct insert order so foreign key constraints are never violated
Plan generation — produces a per-table plan with record counts and descriptions
Review — shows you the plan before any data is written; you approve or refine
Seeding — writes data directly into your tables in dependency order

The review step means you always see exactly what will happen before it happens. If the plan doesn't match what you need, describe what to change — Seedfast replans without restarting the session.

Handling schema changes#

Seedfast reads your live schema every time it runs. If you add a table, rename a column, or add a foreign key, Seedfast picks it up automatically on the next run — no configuration updates needed.

If you provide a --scope that references tables that no longer exist, or omits a table that's now required as a dependency, Seedfast detects this before seeding starts and tells you how to resolve it.

Trigger handling#

Seedfast is aware of database triggers. When seeding, it accounts for triggers that might fire on insert — so the final state of your database reflects both the inserted data and any trigger effects, not just the raw inserts. This means the data you get is consistent with how your application actually writes to the database.

Data Realism Scoping