🌱 seed-master

Generate realistic fake seed data and insert it directly into PostgreSQL, MySQL, or MongoDB — via a single npx command.

✨ Features

• 🗄️ Multi-database — PostgreSQL, MySQL, MongoDB out of the box
• 🧩 Built-in models — users, products, orders, posts, addresses
• 📋 Custom schemas — JSON-driven schema with full @faker-js/faker support
• 📦 Batch insert with real-time progress bar and ETA
• 📤 Multiple outputs — direct DB insert, JSON, SQL, CSV
• 🔗 Relationship support — --ref users:userId to link records
• ⚙️ Config file — seed-master.config.json for project defaults
• 🧪 dummy command — instantly preview fake JSON without any database
• 🛡️ seed command — seed into DB and auto-detect missing tables with a create prompt

📦 Installation

One-time use (no install needed)

npx seed-master dummy users 5
npx seed-master seed users 1000 --connection postgresql://user:pass@localhost:5432/mydb

Install globally

npm install -g seed-master
seed-master dummy products 10
seed-master seed products 500 --connection postgresql://user:pass@localhost:5432/mydb

Install as dev dependency

npm install --save-dev seed-master
npx seed-master seed orders 200 --connection mysql://user:pass@localhost:3306/mydb

🚀 Quick Start

# Preview fake user data instantly (no database needed)
npx seed-master dummy users 5

# Seed 1000 users into PostgreSQL (creates table if missing)
npx seed-master seed users 1000 --connection postgresql://user:pass@localhost:5432/mydb

# Seed 500 products into MySQL
npx seed-master seed products 500 --connection mysql://user:pass@localhost:3306/shop

# Seed 200 orders into MongoDB
npx seed-master seed orders 200 --connection mongodb://localhost:27017/mydb

# Preview a custom schema as JSON
npx seed-master dummy --schema ./my-schema.json 10

# List all available built-in models
npx seed-master list

🧪 dummy — Preview Fake Data (No Database)

The dummy command generates and prints fake JSON to stdout. No database connection required — great for quickly checking what a model's data looks like.

seed-master dummy <model> [count] [--schema <path>]

Examples

# Print 5 fake users as JSON
npx seed-master dummy users 5

# Print 10 fake products (default count is 10)
npx seed-master dummy products

# Preview a custom schema
npx seed-master dummy mymodel 3 --schema ./my-schema.json

# Pipe into a file
npx seed-master dummy orders 100 > orders.json

# Pipe into jq for inspection
npx seed-master dummy users 1 | jq .

Sample output

[
  {
    "id": "b8067702-f98e-4d58-9cbf-706b0ccc8a66",
    "name": "Jeffrey Schaden",
    "email": "[email protected]",
    "phone": "629.390.9628 x227",
    "passwordHash": "7f3fcadde799308a68007d9a57392680ecd5ded27bc9c0c0bdf6710a0bf89fee",
    "avatar": "https://avatars.example.com/154.jpg",
    "createdAt": "2024-09-05T08:26:51.477Z"
  }
]

🛡️ seed — Seed Data into a Database

The seed command inserts fake data directly into your database. It checks whether the target table exists before seeding — and if it doesn't, it asks you whether to create it automatically.

seed-master seed <model> <count> --connection <url> [--batch-size <n>] [--schema <path>]

Table auto-create prompt

If the table does not exist in the database, you will be prompted:

⚠  Table "users" does not exist in the database.
  → Create table "users" now? (y/n): y
✓  Table "users" created successfully.
[████████████████████░░░░] 80% | 800/1000 | ETA: 2s

• Answer y — the table is created automatically based on the model's field types, then seeding continues.
• Answer n — seeding is aborted cleanly with no data written.

Note: For MongoDB, collections are schema-less and auto-created on first insert — no prompt is shown.

Column type inference

When creating a table, seed-master infers column types from the model's field values:

| Value type | PostgreSQL | MySQL | |-----------|-----------|-------| | Integer | INTEGER | INT | | Float/Decimal | NUMERIC | DECIMAL(10,2) | | Boolean | BOOLEAN | TINYINT(1) | | ISO date string | TIMESTAMPTZ | DATETIME | | Everything else | TEXT | TEXT |

Examples

# Seed 1000 users into PostgreSQL
npx seed-master seed users 1000 --connection postgresql://user:pass@localhost:5432/mydb

# Seed 500 products into MySQL
npx seed-master seed products 500 --connection mysql://user:pass@localhost:3306/shop

# Seed 200 orders into MongoDB
npx seed-master seed orders 200 --connection mongodb://localhost:27017/mydb

# Custom batch size
npx seed-master seed posts 10000 --connection postgresql://... --batch-size 500

# Custom schema
npx seed-master seed employees 300 --connection postgresql://... --schema ./employees.json

🗄️ Database Setup

Explicit --connection flag

Pass the URL directly on the command line:

npx seed-master seed users 100 --connection "postgresql://user:pass@localhost:5432/mydb"

Connection URL formats

| Database | Example URL | |---------------|-------------| | PostgreSQL | postgresql://user:pass@localhost:5432/mydb | | MySQL | mysql://user:pass@localhost:3306/mydb | | MongoDB | mongodb://localhost:27017/mydb | | MongoDB Atlas | mongodb+srv://user:[email protected]/mydb |

.env file (for generate command)

Copy .env.example to .env in your project root:

cp .env.example .env

Then set your connection URL:

DATABASE_URL=postgresql://user:pass@localhost:5432/mydb

🧩 Supported Built-in Models

| Model | Fields | |-------------|--------| | users | id, name, email, phone, passwordHash, avatar, createdAt | | products | id, title, price, category, stock, sku, description, imageUrl, createdAt | | orders | id, orderId, userId, total, status, items (JSON), createdAt | | posts | id, title, slug, body, authorId, tags (JSON), published, publishedAt, createdAt | | addresses | id, userId, street, city, state, country, zip, latitude, longitude, type, isPrimary, createdAt |

📋 Custom Schema Guide

Create a JSON file describing your model:

my-schema.json

{
  "model": "employees",
  "fields": {
    "id": "faker.string.uuid",
    "name": "faker.person.fullName",
    "email": "faker.internet.email",
    "salary": "faker.number.int({ min: 30000, max: 120000 })",
    "department": "faker.commerce.department",
    "hireDate": "faker.date.past",
    "isActive": "faker.datatype.boolean"
  }
}

Preview data first with dummy, then seed:

# Preview
npx seed-master dummy --schema ./my-schema.json 5

# Seed into DB
npx seed-master seed employees 500 --connection postgresql://... --schema ./my-schema.json

Supported faker methods

Any method from @faker-js/faker is supported:

{
  "fields": {
    "name":       "faker.person.fullName",
    "email":      "faker.internet.email",
    "age":        "faker.number.int({ min: 18, max: 65 })",
    "city":       "faker.location.city",
    "company":    "faker.company.name",
    "color":      "faker.color.human",
    "sentence":   "faker.lorem.sentence",
    "uuid":       "faker.string.uuid",
    "timestamp":  "faker.date.recent"
  }
}

📤 Output Modes (generate command)

| Mode | Flag | Description | |----------|--------------------|-------------| | insert | --output insert | Default — inserts directly into the database | | json | --output json | Saves to ./seed-output/<model>.json | | sql | --output sql | Saves to ./seed-output/<model>.sql | | csv | --output csv | Saves to ./seed-output/<model>.csv |

🔗 Relationship Support (--ref)

Link generated records to existing records in another table/collection:

# First, seed users
npx seed-master seed users 100 --connection postgresql://...

# Then seed orders, referencing real user IDs
npx seed-master generate orders 200 --db postgres --ref users:userId

The --ref <model>:<field> flag:

1. Fetches up to 10,000 existing id values from the <model> table
2. Randomly assigns them to <field> in each generated record

⚙️ Config File

Create seed-master.config.json at your project root for persistent defaults:

{
  "db": "postgres",
  "connection": "postgresql://user:pass@localhost:5432/mydb",
  "batchSize": 200,
  "defaultOutput": "insert"
}

Priority order: CLI flags > seed-master.config.json > .env > built-in defaults

📊 CLI Reference

Usage: seed-master <command> [options]

Commands:
  dummy <model> [count]              Print fake JSON to stdout — no database needed
  seed <model> <count>               Seed data into a database (prompts to create table if missing)
  generate [model] [count]           Generate and seed fake data (advanced, supports all output modes)
  list                               List all built-in model templates

Options for dummy:
  --schema <path>       Path to custom JSON schema file

Options for seed:
  --connection <url>    Database connection URL  (required)
  --batch-size <n>      Records per batch        [default: 100]
  --schema <path>       Path to custom JSON schema file

Options for generate:
  --db <type>           Database type: postgres | mysql | mongo
  --connection <url>    Database connection URL
  --output <mode>       Output mode: insert | json | sql | csv  [default: insert]
  --batch-size <n>      Records per batch                        [default: 100]
  --schema <path>       Path to custom JSON schema file
  --ref <ref>           Relationship: <model>:<field> (e.g. users:userId)

Global:
  -v, --version         Show version
  -h, --help            Show help

Examples

# ── dummy ─────────────────────────────────────────────────────────────────────
npx seed-master dummy users 5
npx seed-master dummy products
npx seed-master dummy orders 3 | jq .

# ── seed ──────────────────────────────────────────────────────────────────────
npx seed-master seed users 1000 --connection postgresql://user:pass@localhost:5432/mydb
npx seed-master seed products 500 --connection mysql://user:pass@localhost:3306/shop
npx seed-master seed orders 200 --connection mongodb://localhost:27017/mydb
npx seed-master seed posts 10000 --connection postgresql://... --batch-size 500

# ── generate (advanced) ───────────────────────────────────────────────────────
npx seed-master generate users 1000 --output json
npx seed-master generate orders 200 --db mongo --output json
npx seed-master generate --schema ./employees.json 1000 --output csv
npx seed-master generate orders 200 --db postgres --ref users:userId

🛠️ Development

# Clone the repo
git clone https://github.com/your-username/seed-master.git
cd seed-master

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in dev mode (ts-node)
npm run dev -- dummy users 5
npm run dev -- seed users 10 --connection postgresql://user:pass@localhost:5432/mydb

# Type check (no emit)
npm run lint

📁 Project Structure

seed-master/
├── src/
│   ├── cli.ts                     # Entry point — commander setup & all commands
│   ├── types.ts                   # Shared TypeScript interfaces
│   ├── generator/
│   │   ├── index.ts               # Core generation orchestrator
│   │   ├── faker-resolver.ts      # Dot-path → faker value resolver
│   │   └── models/
│   │       ├── users.ts
│   │       ├── products.ts
│   │       ├── orders.ts
│   │       ├── posts.ts
│   │       └── addresses.ts
│   ├── db/
│   │   ├── index.ts               # DB type detection & adapter factory
│   │   ├── postgres.ts            # PostgreSQL adapter (pg) — tableExists, createTable
│   │   ├── mysql.ts               # MySQL adapter (mysql2) — tableExists, createTable
│   │   └── mongo.ts               # MongoDB adapter (mongodb) — auto-creates collections
│   ├── output/
│   │   ├── json.ts
│   │   ├── sql.ts
│   │   └── csv.ts
│   └── utils/
│       ├── config.ts              # Config loading & merging
│       ├── logger.ts              # Chalk-based UX logging
│       └── progress.ts            # cli-progress wrapper
├── bin/
│   └── seed-master.js             # npx shebang entry
├── .env.example
├── seed-master.config.json
├── package.json
└── tsconfig.json

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Commit your changes: git commit -m 'feat: add my feature'
4. Push to the branch: git push origin feat/my-feature
5. Open a Pull Request

Please follow Conventional Commits for commit messages.

📄 License

MIT © seed-master contributors