db-seed skill

# db-seed skill

## When to use

Use this skill when the user wants to:

- Generate realistic fake data for a database table from a YAML schema
- Create SQL INSERT files, JSON fixtures, or CSV files for testing or seeding
- Preview sample rows before generating a full dataset
- Reproduce a dataset exactly using a saved seed value
- Manage and reuse schema definitions across projects

## Prerequisites

- Node.js 20+

## Quick start

```
npx db-seed-generator
```

Dashboard: http://127.0.0.1:7702

## Schema YAML format

```yaml
table: users
count: 100
seed: 42601         # optional - leave out for random
format: sql,json    # optional - overrides default
fields:
  - name: id
    type: uuid
  - name: email
    type: internet.email
    unique: true
  - name: role
    type: enum
    values: [admin, editor, viewer]
  - name: score
    type: number.int
    options:
      min: 0
      max: 100
    nullable: 10    # 10% chance of null
  - name: created_at
    type: date.past
    options:
      years: 2
```

## CLI reference

| Command | Description |
|---------|-------------|
| `db-seed generate <file>` | Generate data from a YAML schema file |
| `db-seed preview <file>` | Print 5 sample rows as JSON without writing files |
| `db-seed validate <file>` | Validate a schema file and print any errors |
| `db-seed list` | List recent generation runs from history |
| `db-seed types` | List all supported field types |
| `db-seed serve` | Start the dashboard server |

## Flags - generate

| Flag | Default | Description |
|------|---------|-------------|
| `--format` | `sql` | Output format(s): `sql`, `json`, `jsonl`, `csv` (comma-separated) |
| `--output-dir` | `./seed-output` | Directory to write output files |
| `--seed` | random | Seed value for reproducible output |
| `--count` | from schema | Override the count in the schema |
| `--overwrite` | - | Overwrite existing output files |
| `--json` | - | Output machine-readable JSON |

## Flags - list

| Flag | Default | Description |
|------|---------|-------------|
| `--limit` | `20` | Maximum number of runs to show |
| `--schema` | all | Filter by schema name |

## Output formats

| Format | Extension | Description |
|--------|-----------|-------------|
| `sql` | `.sql` | Multi-row INSERT statements (500 rows per statement) |
| `json` | `.json` | JSON array of all records |
| `jsonl` | `.jsonl` | One JSON object per line (newline-delimited) |
| `csv` | `.csv` | Header row plus data rows |

## Field type quick reference

| Type | Example output |
|------|----------------|
| `uuid` | `3f8b2e1a-9c4d-4b7e-a2f1-8d5e6c0f1a2b` |
| `internet.email` | `alice.moss@example.com` |
| `internet.url` | `https://example.com/path` |
| `person.firstName` | `Alice` |
| `person.lastName` | `Moss` |
| `person.fullName` | `Alice Moss` |
| `company.name` | `Acme Corp` |
| `phone.number` | `+1-503-555-0100` |
| `number.int` | `74` |
| `number.float` | `19.99` |
| `boolean` | `true` |
| `enum` | value from `values` array |
| `date.past` | `2025-08-14T09:23:11.000Z` |
| `date.future` | `2027-01-22T15:44:00.000Z` |
| `date.recent` | `2026-03-19T18:02:44.000Z` |
| `lorem.sentence` | `Lorem ipsum dolor sit amet.` |
| `lorem.paragraph` | `Lorem ipsum...` (multiple sentences) |
| `string.alphanumeric` | `a8F3Kq` |
| `location.city` | `Portland` |
| `location.country` | `Germany` |
| `location.zipCode` | `97201` |
| `color.human` | `sky blue` |

## Field modifiers

| Modifier | Type | Description |
|----------|------|-------------|
| `nullable` | 0-100 | Probability (%) of generating null for this field |
| `unique` | boolean | Reject duplicate values (up to 10 retries on collision) |
| `options` | object | Passed directly to the faker method (e.g. min/max for numbers) |

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SEED_PORT` | `7702` | Dashboard server port |
| `SEED_DATA_DIR` | `~/.db-seed-generator` | Directory for SQLite history database |
| `SEED_DEFAULT_COUNT` | `100` | Default row count when schema omits `count` |
| `SEED_MAX_COUNT` | `100000` | Maximum allowed row count per run |
| `SEED_DEFAULT_FORMAT` | `sql` | Default output format |
| `SEED_LOG_LEVEL` | `info` | Log level |

## Reproducibility

Every run prints the seed value used. Pass `--seed <value>` to reproduce the exact same dataset.

```
$ db-seed generate users.yaml --seed 42601
ok  seed: 42601
ok  100 rows in 44ms
ok  ~/seed-output/users.sql (12.8 KB)
ok  ~/seed-output/users.json (7.4 KB)
```

## SQL output format

Values are escaped using parameterized value formatting - never string interpolation. Strings are single-quoted with internal single quotes doubled. `null` JS values become SQL `NULL`. Booleans become `1` or `0` (integer). Dates are ISO 8601 strings.

## Troubleshooting

| Symptom | Resolution |
|---------|------------|
| `validation error: unknown type` | Check the type name against `db-seed types` output. Types are case-sensitive |
| `validation error: count exceeds maximum` | Reduce count or increase `SEED_MAX_COUNT` |
| `unique constraint: could not generate unique value` | The field has `unique: true` but the type's value space is too small for the row count. Increase count range or remove `unique` |
| Output file already exists | Use `--overwrite` flag or delete the existing file |
| `enum` field generates wrong values | Verify the `values` array is a list of strings in the YAML |
| Null values in unexpected fields | Check `nullable` percentage - set to `0` to disable nulls |