Core generators

Core generators cover common SQL value families without domain-specific semantics. All stream row by row and are reproducible under a fixed seed.

constant

Alias: const. Argument: optional value, default SQL NULL. Accepts every family. Use it for fixture flags or deliberate fixed labels. Literal values are reported by GEN-SOURCE-VALUES.

generator: { kind: constant, value: active }

YAML booleans and integers retain their types. Other complex YAML values are serialized as text by this minimal coercion layer.

null

No arguments; accepts every family. The target column must be nullable. Prefer null_rate when only some rows should be null.

sequence

Argument	Default	Constraint
start	0	Integer
step	1	Non-zero integer

Accepts integer and big_integer. It is deterministic, unique when the step does not overflow, and usable as a random-access parent key for relationships.

generator: { kind: sequence, start: 1, step: 1 }

copy

Required source names a sibling column. The source must exist and produce a family compatible with the target; it may be declared anywhere, since evaluation follows the read dependency.

columns:
  normalized_email:
    generator: { kind: copy, source: email }
    modifiers: [{ kind: case, mode: lower }]

template

Required parts is a list of literal strings and { field: column_name } references. Accepts text. It concatenates values; it is not an expression or format language.

generator:
  kind: template
  parts: ["INV-", { field: id }, "-", { field: region }]

Every referenced field must exist; each is evaluated before this column automatically, wherever it is declared (see column evaluation order).

slug

Required source names a sibling column; accepts text. Derives a URL slug from that column’s value on the same row: lowercase, every run of non-ASCII-alphanumeric characters collapses to a single -, and leading and trailing dashes are trimmed. Optional max_length (a positive integer) truncates the result, trimming any dash left dangling at the cut. Non-ASCII-alphanumeric characters act as separators; the generator does not transliterate accents or other scripts. The source may be declared anywhere, as evaluation follows the read dependency; add a unique modifier when the slug column is constrained unique.

columns:
  title:
    generator: { kind: string, min_length: 12, max_length: 40 }
  slug:
    generator: { kind: slug, source: title, max_length: 60 }
    modifiers: [{ kind: unique }]

pattern

Required mask; accepts text.

Character	Output
#	decimal digit
?	uppercase ASCII letter
@	lowercase ASCII letter
*	ASCII letter or digit
anything else	literal character

generator: { kind: pattern, mask: "???-####-**" }

database_default

No arguments; accepts every family. Emits SQL DEFAULT and lets the database fill the value. PostgreSQL COPY omits such a column, which requires an actual schema default, identity, or generated expression. A preserved source default can contain literals and therefore participates in GEN-SOURCE-VALUES.

json_value

Optional value, default {}; accepts json. The value must serialize to valid JSON.

generator: { kind: json_value, value: { synthetic: true, tags: [] } }

integer

min defaults to 0; max defaults to 1000. Both bounds are inclusive and min must not exceed max. Accepts integer and big_integer.

decimal

min defaults to 0, max to 1000, and scale to 2. Scale is 0..18, the bounds must be ordered, and the target decimal type must represent them.

generator: { kind: decimal, min: -25.00, max: 250.00, scale: 2 }

boolean

probability is the chance of true, defaults to 0.5, and must be within 0..1. Accepts boolean.

string

min_length defaults to 8; max_length defaults to the minimum. Lengths are non-negative and ordered. Output is ASCII alphanumeric text.

bytes

min_length defaults to 16; max_length defaults to the minimum. Accepts bytes and emits random bytes rather than encoded text.

uuid

No arguments. Emits RFC 4122 version 4 values into uuid or text columns. UUID parent keys can be regenerated by row index for relationship selection.

choice

Required non-empty values; uniform selection. Accepts every family after family-aware coercion.

generator: { kind: choice, values: [draft, active, archived] }

Use it for a small uniform vocabulary. Values are literal and therefore trigger the source-values advisory.

weighted_choice

Required non-empty choices, each containing value and a finite non-negative weight. At least one weight must be positive.

generator:
  kind: weighted_choice
  choices:
    - { value: free, weight: 0.75 }
    - { value: pro, weight: 0.20 }
    - { value: enterprise, weight: 0.05 }

Use it for explicit categorical distributions. It replays literal choices and is always included in GEN-SOURCE-VALUES.