Getting Started
Database Drivers
Schema Integrations
Seed Generators
Utilities and Testing
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.
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.
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.
SeedService inspects the input schema, extracting tables and relationships.SeedService.generatePossibleGenerators..refine()) override default generator choices.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
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.
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.
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.
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,
},
}));Sources: drizzle-seed/src/index.ts:313-344