Seed Engine

Last updated Jul 2, 2026

Relevant source files

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

The "Seed Engine" is a sophisticated data generation framework integrated into the Drizzle ORM ecosystem, specifically designed to automate the population of database schemas with realistic synthetic data. It acts as an abstraction layer between schema definitions and the actual data insertion process, allowing developers to generate consistent, randomized, and relationship-aware data without writing repetitive manual inserts. By leveraging type metadata from Drizzle schemas, the engine intelligently selects appropriate data generators for different SQL column types, ensuring that the generated data respects constraints like foreign keys, uniqueness, and nullability.

The engine functions by analyzing the relational structure of a provided schema to determine the order of operations, ensuring that parent rows are generated before dependent child rows. This dependency management is crucial for maintaining referential integrity during bulk data generation. For complex scenarios involving cyclic dependencies, the Seed Engine employs a two-pass generation strategy, populating initial rows before backfilling circular references.

At its core, the system is built upon a deterministic generation model using the pure-rand library. By accepting a seed value, the engine guarantees that the same input parameters and schema result in identical data sets across multiple runs, which is an essential feature for reproducible testing environments. The Seed Engine is highly extensible, providing a suite of default generators for common data types (names, emails, addresses, integers, etc.) while allowing users to refine the generation strategy for specific columns using a fluent API.

Core Architecture and Data Flow

The Seed Engine operates by transforming schema definitions into a directed graph of generation tasks. It navigates through these tasks by orchestrating a series of generator classes that satisfy column constraints.

Sources: drizzle-seed/src/index.ts:137-206, drizzle-seed/src/services/SeedService.ts:34-76

Generation Lifecycle

The lifecycle of a generation task begins with an initialization phase where generators are assigned a global seed. This seed is propagated to internal pseudo-random number generators (prand.xoroshiro128plus), ensuring that every value generated within a table is statistically independent but deterministically linked to the initial seed argument provided by the developer.

Preparation: SeedService inspects the input schema, extracting tables and relationships.
Ordering: Tables are sorted topologically to respect foreign key constraints via internal methods within SeedService.generatePossibleGenerators.
Refinement: User-provided functions (via .refine()) override default generator choices.
Instantiation: Each column is mapped to a specific generator class based on its SQL type.
Execution: Data is generated in bulk, respecting the requested count.

Sources: drizzle-seed/src/services/Generators.ts:43-50, drizzle-seed/src/services/SeedService.ts:34-76, drizzle-seed/src/services/SeedService.ts:52-67

Generator Hierarchy

The engine utilizes specific generator classes extending from a shared base to enforce a uniform interface. This architecture allows the system to inject specialized versions of generators (like GenerateUniqueInt) when constraints like isUnique are detected during the schema analysis phase.

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

Handling Cyclic Dependencies

One of the most complex features of the Seed Engine is its ability to handle tables that reference each other in a cycle. When the system detects a cycle during the dependency analysis, it performs a two-pass process.

Caution

Seeding cyclic tables with NOT NULL foreign keys is fundamentally problematic. The system will throw an error because it cannot satisfy the circular dependency in a single insertion pass.

The logic for cyclic resolution is orchestrated within SeedService during the table value generation process, specifically identified when relations are marked with isCyclic: true by the internal cycle detection algorithm.

Sources: drizzle-seed/src/services/SeedService.ts:1108-1140

API Surface

The public API is centered around the seed() function, which initializes the process and returns a SeedPromise. This allows for a chainable, type-safe API for refining generator behavior.

Method	Purpose
`seed(db, schema)`	Entry point for triggering the seed engine.
`refine(callback)`	Allows overriding the automatic generator selection.
`reset(db, schema)`	Truncates tables safely (manages FK constraints).

Sources: drizzle-seed/src/index.ts:346-364, drizzle-seed/src/index.ts:441-479

Worked Example

This example demonstrates how to seed a table while refining specific columns to use unique data or custom templates.

// Standard usage of the Seed Engine API
await seed(db, schema, { count: 1000, seed: 42 }).refine((funcs) => ({
  users: {
    columns: {
      // Use unique first names
      name: funcs.firstName({ isUnique: true }),
      // Use custom template for phone numbers
      phone: funcs.phoneNumber({ template: "+380 99 ###-##-##" }),
    },
    count: 500,
  },
}));