---
title: "Seed Service Engine"
description: "The seed service engine is a deterministic test data generation framework built into Drizzle ORM that populates database tables with realistic mock data, handles schema introspection, and executes ..."
last_updated: "2026-10-12T08:14:00.811777+00:00"
canonical_url: "https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/seed-service-engine"
---
Relevant source files
The following files were used as context for generating this wiki page:
- [drizzle-seed/src/services/SeedService.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts)
- [drizzle-seed/src/index.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts)
- [drizzle-kit/src/api.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/api.ts)
- [drizzle-seed/src/services/Generators.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/Generators.ts)
- [drizzle-kit/src/introspect-mysql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-mysql.ts)
- [drizzle-kit/src/serializer/gelSerializer.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/gelSerializer.ts)
- [drizzle-kit/src/serializer/studio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/serializer/studio.ts)
- [drizzle-kit/src/introspect-singlestore.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/introspect-singlestore.ts)
- [drizzle-seed/src/types/seedService.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/seedService.ts)
- [drizzle-seed/type-tests/mysql.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/mysql.ts)
- [drizzle-seed/type-tests/sqlite.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/sqlite.ts)
- [drizzle-kit/src/sqlgenerator.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-kit/src/sqlgenerator.ts)
- [drizzle-seed/type-tests/pg.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/pg.ts)
- [drizzle-seed/src/types/drizzleStudio.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/drizzleStudio.ts)
- [drizzle-seed/src/services/apiVersion.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/apiVersion.ts)
- [drizzle-seed/src/services/utils.ts](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/utils.ts)
## Overview
The seed service engine is a deterministic test data generation framework built into Drizzle ORM that populates database tables with realistic mock data, handles schema introspection, and executes database mutations [[drizzle-seed/src/index.ts:301-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L301-L364), [Seed Data Generators](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/seed-data-generators)]. It provides the core engine behind the Seed Client Interface, bridging TypeScript table definitions and relation metadata with robust random value generators while supporting versioned generator configurations and user-defined refinements [drizzle-seed/src/index.ts:196-205](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L196-L205), [drizzle-seed/src/index.ts:301-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L301-L364), [drizzle-seed/src/services/SeedService.ts:305-337](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L305-L337). The engine addresses complex database population challenges such as foreign key dependencies, cyclic table relations, and type-safe generator mapping across multiple SQL dialects [[drizzle-seed/src/services/SeedService.ts:339-483](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L339-L483), [drizzle-seed/src/services/SeedService.ts:503-991](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L503-L991), [Database Introspection](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/database-introspection), [Migration Toolkit Schema](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/migration-toolkit-schema)]. By employing topological sorting for insertion ordering and deferred updates for cyclic references, the engine enables reliable batch seeding and resetting for PostgreSQL, MySQL, and SQLite databases [[drizzle-seed/src/services/SeedService.ts:375-422](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L375-L422), [drizzle-seed/src/services/SeedService.ts:911-961](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L911-L961), [Studio Server Bridge](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/migration-toolkit/studio-server-bridge)].
Sources: [drizzle-seed/src/index.ts:196-205](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L196-L205), [drizzle-seed/src/index.ts:301-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L301-L364), [drizzle-seed/src/services/SeedService.ts:305-337](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L305-L337), [drizzle-seed/src/services/SeedService.ts:339-483](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L339-L483), [drizzle-seed/src/services/SeedService.ts:503-991](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L503-L991)
## Seed Client Interface
The public client interface for the seed service engine centers around the top-level `seed()` and `reset()` entrypoint functions, which accept a database connection, a schema definition object, and an optional configuration object [drizzle-seed/src/index.ts:346-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L346-L364), [drizzle-seed/type-tests/mysql.ts:4](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/type-tests/mysql.ts#L4). The `seed()` function returns a `SeedPromise` instance, enabling promise chaining and invocation of the `.refine()` method [drizzle-seed/src/index.ts:310-363](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L310-L363). The `.refine()` method accepts a callback function providing versioned generator functions (`funcs`), allowing users to customize column-level mock data generation and table row counts [drizzle-seed/src/index.ts:196-205](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L196-L205), [drizzle-seed/src/index.ts:324-342](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L324-L342).
```typescript
export function seed<
DB extends
| PgDatabase
| MySqlDatabase
| BaseSQLiteDatabase,
SCHEMA extends {
[key: string]:
| PgTable
| PgSchema
| MySqlTable
| MySqlSchema
| SQLiteTable
| Relations
| any;
},
VERSION extends '2' | '1' | undefined,
>(db: DB, schema: SCHEMA, options?: { count?: number; seed?: number; version?: VERSION }) {
return new SeedPromise(db, schema, options);
}
```
Sources: [drizzle-seed/src/index.ts:346-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L346-L364)
The options object supports a global `count` parameter specifying the default number of rows to generate per table, a deterministic `seed` number to control the pseudo-random number generator state, and a `version` string (`'1'` or `'2'`) selecting between generator function API versions [drizzle-seed/src/index.ts:196-210](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L196-L210), [drizzle-seed/src/index.ts:304-309](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L304-L309), [drizzle-seed/src/index.ts:362](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L362). When `options.version` is undefined or set to `'2'`, the engine resolves generator functions from `generatorsFuncsV2`; otherwise, it uses legacy `generatorsFuncs` [drizzle-seed/src/index.ts:200-202](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L200-L202), [drizzle-seed/src/index.ts:208-210](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L208-L210).
> [!NOTE]
> Passing an explicit `seed` number guarantees deterministic data generation: running the seeding script multiple times with the same seed value yields identical database content, provided the schema and refinement definitions remain unchanged [drizzle-seed/src/index.ts:308](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L308).
Sources: [drizzle-seed/src/index.ts:308](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L308)
| Option Key | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `count` | `number` | `undefined` | Number of rows to generate per table globally. |
| `seed` | `number` | `undefined` | Seed value controlling the pseudo-random generator state. |
| `version` | `'1' \| '2'` | `undefined` | Version specifier (`'2'` maps to `generatorsFuncsV2`, `'1'` maps to `generatorsFuncs`). |
Sources: [drizzle-seed/src/index.ts:196-210](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L196-L210), [drizzle-seed/src/index.ts:304-309](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L304-L309), [drizzle-seed/src/index.ts:362](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L362)
```mermaid
sequenceDiagram
participant User
participant seed as seed()
participant SeedPromise
participant seedFunc
User->>seed: seed(db, schema, options)
seed->>SeedPromise: new SeedPromise(db, schema, options)
User->>SeedPromise: .refine(callback)
SeedPromise->>seedFunc: seedFunc(db, schema, options, refinements)
seedFunc-->>User: Promise
```
Sources: [drizzle-seed/src/index.ts:196-205](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L196-L205), [drizzle-seed/src/index.ts:346-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L346-L364)
## Dialect Schema Inspection
The dialect schema inspection phase processes database schemas and metadata representations from Drizzle Studio or active database connections, transforming raw table definitions into standardized internal models [drizzle-seed/src/index.ts:216-260](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L216-L260), [drizzle-seed/src/index.ts:366-380](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L366-L380). When seeding via Drizzle Studio objects, the engine iterates over schemas, tables, and columns, extracting properties such as column names, data types, nullability, defaults, uniqueness constraints, and primary keys [drizzle-seed/src/index.ts:238-260](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L238-L260). Composite primary keys and column-level primary flags populate the table's primary key list [drizzle-seed/src/index.ts:258](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L258).
```typescript
export type DbPrimaryKey = {
name: string;
columns: string[];
};
export type DbForeignKey = {
name: string;
tableFrom: string;
columnsFrom: string[];
schemaFrom: string;
schemaTo: string;
tableTo: string;
columnsTo: string[];
onUpdate?: string;
onDelete?: string;
};
```
Sources: [drizzle-seed/src/types/drizzleStudio.ts:1-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/drizzleStudio.ts#L1-L16)
For relational wiring, `seedForDrizzleStudio` extracts and filters Drizzle Studio relations where the relation type is `'one'` and matches the target schema boundaries [drizzle-seed/src/index.ts:237](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L237), [drizzle-seed/src/index.ts:263](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L263). It evaluates reciprocal relation pairs to detect cyclic dependencies, tagging each relation with an `isCyclic` boolean flag before generating possible column generators [drizzle-seed/src/index.ts:264-285](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L264-L285). MySQL table filtering filters schema entries to isolate `MySqlTable` and `Relations` instances, mapping database table names back to their TypeScript counterparts via `getTableName` [drizzle-seed/src/index.ts:886-928](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L886-L928), [drizzle-seed/src/index.ts:963-973](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L963-L973).
| Property | Type | Description |
| :--- | :--- | :--- |
| `name` | `string` | Constraint identifier name. |
| `columnsFrom` / `columnsTo` | `string[]` | Source and target columns involved in the foreign key relationship. |
| `schemaFrom` / `schemaTo` | `string` | Source and target database schema names. |
| `tableFrom` / `tableTo` | `string` | Source and target table names. |
| `onUpdate` / `onDelete` | `string` (optional) | Referential action rules for updates and deletes. |
Sources: [drizzle-seed/src/types/drizzleStudio.ts:6-16](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/drizzleStudio.ts#L6-L16)
> [!NOTE]
> Relations are filtered specifically for `'one'` types during Drizzle Studio seeding initialization to correctly build structural parent-child table trees before generating row data [drizzle-seed/src/index.ts:237](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L237).
Sources: [drizzle-seed/src/index.ts:237](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L237)
## Dependency Graph Ordering
The engine determines insertion sequence by inspecting table relationships and analyzing inbound and outbound dependency edges [drizzle-seed/src/services/SeedService.ts:424-483](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L424-L483). The method `getInfoFromRelations` aggregates relation arrays into a lookup map containing inbound and outbound counts, self-reference flags, and sets of required or dependent table names [drizzle-seed/src/services/SeedService.ts:424-480](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L424-L480). Leaf tables—defined as those with zero outbound relations or where all outbound edges are self-references—seed the initial queue for topological sorting [drizzle-seed/src/services/SeedService.ts:378-385](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L378-L385).
```typescript
getOrderedTablesList = (
tablesInOutRelations: ReturnType['tablesInOutRelations'],
): string[] => {
const leafTablesNames = Object.entries(tablesInOutRelations)
.filter(
(tableRel) =>
tableRel[1].out === 0
|| (tableRel[1].out !== 0
&& tableRel[1].selfRelCount === tableRel[1].out),
)
.map((tableRel) => tableRel[0]);
const orderedTablesNames: string[] = [];
let parent: string, children: string[];
for (let i = 0; leafTablesNames.length !== 0; i++) {
parent = leafTablesNames.shift() as string;
if (orderedTablesNames.includes(parent)) {
continue;
}
if (tablesInOutRelations[parent] === undefined) {
orderedTablesNames.push(parent);
continue;
}
for (const orderedTableName of orderedTablesNames) {
tablesInOutRelations[parent]!.requiredTableNames.delete(orderedTableName);
}
if (
tablesInOutRelations[parent]!.requiredTableNames.size === 0
|| equalSets(
tablesInOutRelations[parent]!.requiredTableNames,
tablesInOutRelations[parent]!.dependantTableNames,
)
) {
orderedTablesNames.push(parent);
} else {
leafTablesNames.push(...tablesInOutRelations[parent]!.requiredTableNames, parent);
continue;
}
children = [...tablesInOutRelations[parent]!.dependantTableNames];
leafTablesNames.push(...children);
}
return orderedTablesNames;
};
```
Sources: [drizzle-seed/src/services/SeedService.ts:375-422](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L375-L422)
Cyclic relations are evaluated via depth-first search in `isRelationCyclic` to identify back-edges, and `cyclicTablesCompare` resolves ordering priority between tables involved in circular dependencies [drizzle-seed/src/services/SeedService.ts:339-373](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L339-L373), [drizzle-seed/src/services/SeedService.ts:832-864](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L832-L864). If both tables in a cyclic pair contain `notNull` foreign key columns, the engine rejects the schema configuration, as circular non-null constraints prevent sequential insertion [drizzle-seed/src/services/SeedService.ts:355-360](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L355-L360).
| Relation Property | Type | Description |
| :--- | :--- | :--- |
| `out` | `number` | Count of outbound foreign key references originating from the table. |
| `in` | `number` | Count of inbound foreign key references pointing to the table. |
| `selfRelation` | `boolean` | Indicates whether the relation references the table itself. |
| `selfRelCount` | `number` | Number of columns involved in a self-reference. |
| `requiredTableNames` | `Set` | Set of prerequisite tables that must be seeded first. |
| `dependantTableNames` | `Set` | Set of dependent tables requiring this table's primary keys. |
Sources: [drizzle-seed/src/services/SeedService.ts:425-433](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L425-L433)
> [!CAUTION]
> Attempting to seed cyclic tables where both tables contain `notNull` foreign key columns triggers an immediate error, because neither table can be populated first without violating constraints [drizzle-seed/src/services/SeedService.ts:355-360](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L355-L360).
Sources: [drizzle-seed/src/services/SeedService.ts:355-360](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L355-L360)
## Column Generator Selection
### Version Selection and Generator Mapping
The seed engine maps column data types, base types, and uniqueness constraints to concrete generator instances by invoking dialect-specific pickers like `selectGeneratorForSqlite` and `selectGeneratorForPostgresColumn`. Once an initial generator is instantiated, `replaceIfUnique` handles columns with uniqueness constraints by substituting specialized unique variant generators [drizzle-seed/src/services/SeedService.ts:283-286](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L283-L286). The resulting generator instance is then passed to `selectVersionOfGenerator`, which inspects the entity kind and resolves constructors defined in `generatorsMap` according to the active API version [drizzle-seed/src/services/SeedService.ts:289](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L289), [drizzle-seed/src/services/SeedService.ts:305-316](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L305-L316).
```typescript
selectVersionOfGenerator = (generator: AbstractGenerator) => {
const entityKind = generator.getEntityKind();
if (entityKind === 'GenerateArray') {
const oldBaseColumnGen = (generator as GenerateArray).params.baseColumnGen;
const newBaseColumnGen = this.selectVersionOfGenerator(oldBaseColumnGen);
// newGenerator.baseColumnDataType = oldGenerator.baseColumnDataType;
(generator as GenerateArray).params.baseColumnGen = newBaseColumnGen;
}
const possibleGeneratorConstructors = generatorsMap[entityKind as keyof typeof generatorsMap];
const possibleGeneratorConstructorsFiltered = possibleGeneratorConstructors?.filter((possGenCon) =>
possGenCon.version <= this.version! // sorting in ascending order by version
).sort((a, b) => a.version - b.version);
const generatorConstructor = possibleGeneratorConstructorsFiltered?.at(-1) as
| (new(params: any) => AbstractGenerator)
| undefined;
if (generatorConstructor === undefined) {
throw new Error(`Can't select ${entityKind} generator for ${this.version} version.`);
}
const newGenerator = new generatorConstructor(generator.params);
newGenerator.baseColumnDataType = generator.baseColumnDataType;
newGenerator.isUnique = generator.isUnique;
// TODO: for now only GenerateValuesFromArray support notNull property
newGenerator.notNull = generator.notNull;
newGenerator.dataType = generator.dataType;
newGenerator.stringLength = generator.stringLength;
return newGenerator;
};
```
Sources: [drizzle-seed/src/services/SeedService.ts:305-337](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L305-L337)
The latest supported engine version is tracked as a constant, and filtering logic sorts available generator constructors in ascending order by version, selecting the highest version that does not exceed `this.version` [drizzle-seed/src/services/SeedService.ts:316-321](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L316-L321), [drizzle-seed/src/services/apiVersion.ts:1-1](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/apiVersion.ts#L1-L1). For nested structures such as `GenerateArray`, the version selection procedure recursively traverses and resolves base column generators before instantiating the wrapper [drizzle-seed/src/services/SeedService.ts:307-314](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L307-L314).
| Property / Field | Type | Description |
| :--- | :--- | :--- |
| `columnName` | `string` | Target column name in the database schema. |
| `generator` | `AbstractGenerator \| undefined` | Active mock data generator assigned to the column. |
| `isUnique` | `boolean` | Flag indicating whether uniqueness constraints apply. |
| `notNull` | `boolean` | Flag indicating whether null values are forbidden. |
| `primary` | `boolean` | Flag indicating whether the column forms part of the primary key. |
| `generatedIdentityType` | `'always' \| 'byDefault' \| undefined` | Identity generation strategy for auto-incrementing columns. |
| `wasRefined` | `boolean` | Indicates if the generator was modified by user refinements. |
| `wasDefinedBefore` | `boolean` | Tracking flag for prior definition state. |
| `isCyclic` | `boolean` | Indicates involvement in a cyclic table relationship. |
Sources: [drizzle-seed/src/types/seedService.ts:14-24](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/types/seedService.ts#L14-L24)
> [!NOTE]
> When selecting generator versions, if `possibleGeneratorConstructorsFiltered` finds no matching constructor for the requested version, an explicit error is thrown indicating that the generator cannot be selected [drizzle-seed/src/services/SeedService.ts:324-326](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L324-L326).
Sources: [drizzle-seed/src/services/SeedService.ts:324-326](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L324-L326)
### SQLite Column Type Selection Rules
For SQLite schemas, `selectGeneratorForSqlite` inspects primary keys, column types, and data types to assign the appropriate generator instance [drizzle-seed/src/services/SeedService.ts:993-997](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L993-L997). Integer primary keys map directly to `GenerateIntPrimaryKey`, whereas boolean flags and timestamps map to `GenerateBoolean` and `GenerateTimestamp` respectively [drizzle-seed/src/services/SeedService.ts:999-1015](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L999-L1015). Numeric columns with precision and scale parameters calculate a `maxAbsoluteValue` to bound `GenerateNumber` parameters [drizzle-seed/src/services/SeedService.ts:1026-1038](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L1026-L1038).
```typescript
selectGeneratorForSqlite = (
table: Table,
col: Column,
) => {
const pickGenerator = (table: Table, col: Column) => {
// int section ---------------------------------------------------------------------------------------
if (
(col.columnType === 'integer' || col.columnType === 'numeric')
&& table.primaryKeys.includes(col.name)
) {
const generator = new generatorsMap.GenerateIntPrimaryKey[0]();
return generator;
}
if (col.columnType === 'integer' && col.dataType === 'boolean') {
const generator = new generatorsMap.GenerateBoolean[0]();
return generator;
}
if ((col.columnType === 'integer' && col.dataType === 'date')) {
const generator = new generatorsMap.GenerateTimestamp[0]();
return generator;
}
if (
col.columnType === 'integer'
|| (col.dataType === 'bigint' && col.columnType === 'blob')
) {
const generator = new generatorsMap.GenerateInt[0]();
return generator;
}
// number section ------------------------------------------------------------------------------------
if (col.columnType.startsWith('real') || col.columnType.startsWith('numeric')) {
if (col.typeParams.precision !== undefined) {
const precision = col.typeParams.precision;
const scale = col.typeParams.scale === undefined ? 0 : col.typeParams.scale;
const maxAbsoluteValue = Math.pow(10, precision - scale) - Math.pow(10, -scale);
const generator = new generatorsMap.GenerateNumber[0]({
minValue: -maxAbsoluteValue,
maxValue: maxAbsoluteValue,
precision: Math.pow(10, scale),
});
return generator;
}
const generator = new generatorsMap.GenerateNumber[0]();
return generator;
}
```
Sources: [drizzle-seed/src/services/SeedService.ts:993-1043](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L993-L1043)
Text, numeric, and blob columns undergo pattern matching against column names to assign domain-specific generators such as `GenerateFirstName` and `GenerateEmail`, falling back to `GenerateString` or `GenerateUniqueString` depending on primary key status [drizzle-seed/src/services/SeedService.ts:1045-1083](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L1045-L1083).
| Column Condition | Column Type / Metadata | Assigned Generator |
| :--- | :--- | :--- |
| Primary Key Integer | `integer` / `numeric` + primary key | `GenerateIntPrimaryKey` |
| Boolean Flag | `integer` + `dataType: 'boolean'` | `GenerateBoolean` |
| Timestamp | `integer` + `dataType: 'date'` | `GenerateTimestamp` |
| Standard Integer | `integer` / `blob` (`bigint`) | `GenerateInt` |
| Bounded Number | `real` / `numeric` + precision params | `GenerateNumber` (with custom bounds) |
| Unique Text | `text` / `numeric` / `blob` + primary key | `GenerateUniqueString` |
| Name Field | `text` / `numeric` / `blob` + name includes `'name'` | `GenerateFirstName` |
| Email Field | `text` / `numeric` / `blob` + name includes `'email'` | `GenerateEmail` |
Sources: [drizzle-seed/src/services/SeedService.ts:999-1073](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L999-L1073)
> [!WARNING]
> Property propagation during version selection currently copies `notNull`, `dataType`, and `stringLength` properties, but the engine notes that only `GenerateValuesFromArray` fully supports runtime enforcement of the `notNull` property [drizzle-seed/src/services/SeedService.ts:291-293](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L291-L293), [drizzle-seed/src/services/SeedService.ts:331-333](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L331-L333).
Sources: [drizzle-seed/src/services/SeedService.ts:291-293](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L291-L293), [drizzle-seed/src/services/SeedService.ts:331-333](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L331-L333)
## Database Mutation Execution
### Cyclic Table Validation and Ordering
Before executing record generation and database insertion, `seedMySql` inspects schema relationships to identify cyclic dependencies [drizzle-seed/src/index.ts:926-928](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L926-L928). When tables participate in cyclic relationships, `preserveCyclicTablesData` is enabled to manage foreign key constraints across interdependent entities [drizzle-seed/src/index.ts:939-946](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L939-L946).
> [!CAUTION]
> `cyclicTablesCompare` explicitly throws an error if two cyclic tables both contain `notNull` foreign key columns, as the engine cannot seed cyclic relationships with mandatory foreign keys [drizzle-seed/src/services/SeedService.ts:355-359](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L355-L359).
Sources: [drizzle-seed/src/services/SeedService.ts:355-359](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L355-L359)
```typescript
cyclicTablesCompare = (
table1: Table,
table2: Table,
relation: Relation & { isCyclic: boolean },
reverseRelation: Relation & { isCyclic: boolean } | undefined,
) => {
// TODO: revise
const hasTable1NotNullColumns = relation.columns.some((colIName) =>
table1.columns.find((colJ) => colJ.name === colIName)?.notNull === true
);
if (reverseRelation !== undefined) {
const hasTable2NotNullColumns = reverseRelation.columns.some((colIName) =>
table2.columns.find((colJ) => colJ.name === colIName)?.notNull === true
);
if (hasTable1NotNullColumns && hasTable2NotNullColumns) {
throw new Error(
`The '${table1.name}' and '${table2.name}' tables have not null foreign keys. You can't seed cyclic tables with not null foreign key columns.`,
);
}
if (hasTable1NotNullColumns) return 1;
else if (hasTable2NotNullColumns) return -1;
return 0;
}
```
Sources: [drizzle-seed/src/services/SeedService.ts:339-364](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/services/SeedService.ts#L339-L364)
### Table Value Generation and Insertion Pipeline
`SeedService` drives the generation of record values across ordered topological tables and handles subsequent filtering of cyclic relations to perform secondary updates [drizzle-seed/src/index.ts:941-960](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L941-L960). For MySQL environments, `resetMySql` temporarily disables foreign key checks by executing `SET FOREIGN_KEY_CHECKS = 0;`, truncates each target table using raw SQL statements, and restores foreign key checks with `SET FOREIGN_KEY_CHECKS = 1;` before inserting generated batches [drizzle-seed/src/index.ts:867-884](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L867-L884).
| Step | Action | Execution Details |
| :--- | :--- | :--- |
| 1 | Table Filtering & Info Extraction | Filters schema definitions into valid MySQL tables and relations via `filterMysqlTables` and `getMySqlInfo` [drizzle-seed/src/index.ts:926-927](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L926-L927). |
| 2 | Initial Value Generation | Generates initial table values via `generateTablesValues` with cyclic preservation enabled [drizzle-seed/src/index.ts:941-947](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L941-L947). |
| 3 | Cyclic Filtering | Filters cyclic table generators using `filterCyclicTables` to isolate unique non-null columns needing deferred updates [drizzle-seed/src/index.ts:949-952](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L949-L952). |
| 4 | Secondary Database Update | Executes subsequent row updates in the database when filtered generators are present [drizzle-seed/src/index.ts:954-960](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L954-L960). |
Sources: [drizzle-seed/src/index.ts:926-960](https://github.com/blade47/drizzle-orm/blob/48e5406027103a9fca6eb66417187c4a8b5c6aa3/drizzle-seed/src/index.ts#L926-L960)
## Related
- [Seed Data Generators](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/ecosystem-packages/seed-data-generators)
- [Table and Column Models](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/technical/core-architecture/table-and-column-models)
## Sitemap
See the full [sitemap](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/llms.txt) for all pages in this wiki.