Data Generators

Last updated Jul 2, 2026

Relevant source files

The following files were used as context for generating this wiki page:

Data Generators are the backend mechanism for producing high-quality, randomized, and schema-compliant data for database tables within the seeding process. Their primary purpose is to encapsulate the logic for generating realistic datasets—such as names, emails, dates, or complex structures like JSON and arrays—into reusable, configurable classes. By utilizing deterministic pseudo-random number generation via the pure-rand library, these components ensure that seeding results can be stable and reproducible given the same input seed.

The system is built around a class structure where each generator handles specific data types. Key classes such as GenerateArray, GenerateInt, and GenerateEmail define a consistent lifecycle, providing an init method for parameter setup and a generate method for production. This architecture allows the system to differentiate between standard and specialized variants, handle array transformations, and manage dependencies like foreign key resolution. By mapping specific column requirements to these specialized classes, the system effectively bridges the gap between raw database schemas and concrete data instances.

Data Generators interact closely with the SeedService, which orchestrates the seeding process by inspecting tables, resolving relations, and applying user-defined refinements. When a table is processed, the SeedService identifies the appropriate generator for each column, replaces it with an "array" or "unique" variant if needed, and manages the dependency flow to ensure that referenced data is available before it is required. This design ensures that the seeding process remains robust against complex schema requirements, including self-referential relations and not-null constraints.

Generator Lifecycle and Mechanics

Every generator class must implement an init method to process initial parameters (like count and seed) and a generate method that returns a value based on the current context (i).

The operational sequence for a generator typically follows:

Initialization: init({ count, seed }) is invoked to prepare internal state, such as seeding the PRNG instance and allocating caches like integersCount for unique value tracking.
Transformation: The system utilizes helper methods like replaceIfUnique() and replaceIfArray() to swap standard generators for specialized instances (e.g., GenerateUniqueInt or GenerateArray) when the database column constraints dictate specific behavior.
Production: The generate() method is executed for each row, producing a value consistent with the column's defined type.

Sources: drizzle-seed/src/services/Generators.ts:43-109

Generator Registry and Creation

The system defines generator behaviors using a factory-based approach. The createGenerator utility function facilitates the instantiation of these classes, mapping parameters to the appropriate constructor logic.

function createGenerator<GeneratorType extends AbstractGenerator<T>, T>(
	generatorConstructor: new(params?: T) => GeneratorType,
) {
	return (
		...args: GeneratorType extends GenerateValuesFromArray | GenerateDefault | WeightedRandomGenerator ? [T]
			: ([] | [T])
	): GeneratorType => {
		let params = args[0];
		if (params === undefined) params = {} as T;
		return new generatorConstructor(params);
	};
}

Sources: drizzle-seed/src/services/GeneratorFuncs.ts:56-67

Additionally, the system maintains a generatorsMap object that maps generator kinds to their historical and current versions. This allows the internal SeedService to select the correct implementation based on the specified API version requirement.

Sources: drizzle-seed/src/services/GeneratorFuncs.ts:764-918

Unique Data Generation Mechanism

To guarantee uniqueness (e.g., for Primary Keys or isUnique: true columns), the system provides specialized classes like GenerateUniqueInt. The core mechanism for ensuring uniqueness relies on interval-based selection:

The generator maintains a state of intervals—ranges of integers that have not yet been consumed.
When generate() is called, it picks a random interval, selects a value, and modifies the interval state (splitting or removing ranges) to reflect that the value is now claimed.
This approach avoids the memory overhead of storing every generated value while maintaining strictly unique outputs.

Caution

If the count provided to GenerateUniqueInt exceeds the number of available unique values in a range, the generator will throw a RangeError. Always ensure the defined minValue and maxValue range is sufficient for the requested count.

Sources: drizzle-seed/src/services/Generators.ts:643-813

Array and Complex Type Production

The GenerateArray class handles columns defined as arrays. It does not generate data directly; rather, it acts as a container for a baseColumnGen.

Recursion: The system supports nested arrays by initializing a GenerateArray that contains another GenerateArray.
Propagation: During initialization, the parent array generator calculates the total elements required (count * size) and propagates the appropriate parameters to the nested generator.

Sources: drizzle-seed/src/services/Generators.ts:112-130

Design Trade-offs

Design Choice	Benefit	Cost
`pure-rand` RNG	Deterministic and reproducible seeding across runs.	Slightly higher complexity than standard `Math.random()`.
Wrapper/Decorator Pattern	Keeps `GenerateArray` logic separate from data logic.	Increased object overhead for nested arrays.
Interval-based Unique Gen	Guarantees uniqueness without memory-heavy lookups.	More complex logic for managing overlapping/disjoint range splits.

Sources: drizzle-seed/src/services/Generators.ts:2, 643-813, 112-130

Worked Example

This example demonstrates how a user refines a column using a WeightedRandomGenerator, which combines different probability-based sources for column values.

import { seed } from 'drizzle-seed';
 
await seed(db, schema, { count: 1000 }).refine((funcs) => ({
  posts: {
    columns: {
      content: funcs.weightedRandom([
        {
          weight: 0.6,
          value: funcs.loremIpsum({ sentencesCount: 3 }),
        },
        {
          weight: 0.4,
          value: funcs.default({ defaultValue: "TODO" }),
        },
      ]),
    },
  },
}));