Generator reference

A generator owns one column and produces its base value. The compiler checks the generator’s accepted SQL families and validates its arguments. Modifiers run afterward in the order declared.

Column evaluation order

When a generator reads sibling columns on the same row — copy, template, slug, and before/after do — the engine evaluates each column after the columns it reads, following the read dependencies rather than the order columns are declared. A derived column may therefore appear anywhere in the schema, before or after its source. A read whose source has not been produced yet (or a generator reading its own column) sees no value; a set of columns that read each other in a cycle is rejected at compile time as GEN-COLUMN-CYCLE. Columns that read nothing keep their declared schema order.

columns:
  email:
    generator: { kind: internet.email }
    modifiers:
      - { kind: case, mode: lower }
      - { kind: unique, max_attempts: 20 }

Choose by intent

Need	Start with
IDs and deterministic counters	sequence, uuid, monotonic
Bounded random primitives	integer, decimal, boolean, string
Realistic domain-shaped text	Semantic generators
Passwords, tokens, and secrets	Credential generators
Preserve an observed distribution	Observed and statistical generators
Foreign-key values	Relationship generators or a planner
Derive from another column	copy, template, before/after
Let the database fill the value	database_default

Common rules

• kind is required and must name a registered generator or alias.
• Unknown arguments are rejected. Required arguments are checked by both the published schema and the compiler.
• A generator can attach only to a compatible schema.columns[].family.
• Cross-column generators may read only columns that exist and are ordered before them without forming a dependency cycle.
• Every generator is deterministic under a fixed seed unless its documentation explicitly says otherwise. All current built-ins are deterministic.
• A generator that embeds literal choices can trigger the non-fatal GEN-SOURCE-VALUES advisory. See Privacy.

Catalog

• Core — primitives, categorical values, templates, IDs, and defaults
• Semantic — names, addresses, internet, commerce, temporal, and file shapes
• Credentials — synthetic-only secrets and placeholders
• Observed and statistical — samples, histograms, distributions, and monotonic values
• Relationships — ordinary and composite foreign keys

For correlated multi-column or cross-table invariants, use a planner instead of independent generators.