---
title: "Seed Engine"
description: "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 synthet..."
last_updated: "2026-07-02T09:35:18.649651+00:00"
canonical_url: "https://www.doc0.app/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/seed-generators/seed-engine"
---

<details>
<summary>Relevant source files</summary>

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

- [drizzle-seed/src/services/Generators.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/services/Generators.ts)
- [drizzle-seed/src/index.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/index.ts)
- [drizzle-seed/src/services/SeedService.ts](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/services/SeedService.ts)
</details>

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.

```mermaid
flowchart TD
    A["User Input<br>(Schema + Options)"] --> B["SeedPromise<br>(Entry)"]
    B --> C["SeedService<br>(Dependency Graph)"]
    C --> D["Generator Initialization<br>(Seed & Weights)"]
    D --> E["Dependency Sort<br>(Cyclic Resolution)"]
    E --> F["Table Data Generation"]
    F --> G["DB Insertion"]
    
    subgraph Generators
    H["Generator Classes<br>(GenerateInt, GenerateEmail, etc.)"]
    end
    D -.-> H
```
Sources: [drizzle-seed/src/index.ts:137-206](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/index.ts#L137-L206), [drizzle-seed/src/services/SeedService.ts:34-76](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/services/SeedService.ts#L34-L76)

## 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.

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

Sources: [drizzle-seed/src/services/Generators.ts:43-50](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/services/Generators.ts#L43-L50), [drizzle-seed/src/services/SeedService.ts:34-76](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/services/SeedService.ts#L34-L76), [drizzle-seed/src/services/SeedService.ts:52-67](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/services/SeedService.ts#L52-L67)

## 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.

```mermaid
classDiagram
    class GenerateInt {
        +init()
        +generate()
    }
    class GenerateUniqueInt {
        +init()
        +generate()
    }
    GenerateInt ..> GenerateUniqueInt : creates
```
Sources: [drizzle-seed/src/services/Generators.ts:17-109](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/services/Generators.ts#L17-L109)

## 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](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/services/SeedService.ts#L1108-L1140)

## 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](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/index.ts#L346-L364), [drizzle-seed/src/index.ts:441-479](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/index.ts#L441-L479)

## Worked Example

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

```typescript
// 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](https://github.com/blade47/drizzle-orm/blob/main/drizzle-seed/src/index.ts#L313-L344)

## Related

- [Data Generators](https://www.doc0.app/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/seed-generators/data-generators)


## Sitemap

See the full [sitemap](https://www.doc0.app/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/llms.txt) for all pages in this wiki.