drizzle-seed

library0.3.1jsnpmunverified

Drizzle Seed is a TypeScript library designed for generating deterministic, yet realistic, fake data to populate databases in conjunction with Drizzle ORM. It leverages a seedable pseudorandom number generator (pRNG) to ensure that generated data is consistent and reproducible across different runs, which is crucial for reliable testing, development, and debugging workflows. The library currently stands at version 0.3.1 (within the Drizzle ecosystem's 0.x series for utilities), with ongoing active development that typically follows the release cadence and advancements of Drizzle ORM. Key differentiators include its tight integration with Drizzle ORM's type safety, its focus on reproducible data sets via pRNG, and a flexible API for refining data generation at column and table levels, including handling complex relationships. It enables developers to easily reset and re-seed their databases with predictable data.

database testing serialization

npm install drizzle-seed

github ↗package ↗

INSTALL

IMPORT

SIG · DRIZZLE-SEED

drizzle-seed

databasejavascriptv0.3.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

seed

✓ import { seed } from 'drizzle-seed';

✗ import seed from 'drizzle-seed'; // Not a default export

The primary function for initiating the seeding process. Always a named import.

reset

✓ import { reset } from 'drizzle-seed';

✗ const reset = require('drizzle-seed').reset; // CommonJS is supported but ESM is preferred.

Used to clear tables before seeding, typically imported alongside `seed`.

Fake

✓ import { seed, Fake } from 'drizzle-seed';

Though not exported directly as `Fake`, the `refine` callback receives a 'faker' object, often conceptually referred to as the 'Fake' data generator. For direct column value generation, the `refine` function provides helper methods rather than a top-level `Fake` export. The `f` argument in `refine((f) => ...)` is an instance of the internal faker.

This quickstart demonstrates how to define a Drizzle schema, connect to a PostgreSQL database, then use `reset` to clear tables and `seed` to populate them with deterministic fake data, including related entities. It shows column-level data generation and `with` for relations.

import 'dotenv/config'; import { pgTable, serial, text, timestamp, integer } from 'drizzle-orm/pg-core'; import { drizzle } from 'drizzle-orm/node-postgres'; import { Pool } from 'pg'; import { seed, reset } from 'drizzle-seed'; export const users = pgTable('users', { id: serial('id').primaryKey(), name: text('name').notNull(), email: text('email').notNull().unique(), age: integer('age').notNull(), createdAt: timestamp('created_at').notNull().defaultNow(), }); export const posts = pgTable('posts', { id: serial('id').primaryKey(), title: text('title').notNull(), content: text('content'), userId: integer('user_id').references(() => users.id, { onDelete: 'cascade' }).notNull(), createdAt: timestamp('created_at').notNull().defaultNow(), }); const pool = new Pool({ connectionString: process.env.DATABASE_URL ?? 'postgresql://user:password@localhost:5432/drizzle_test_db', }); const db = drizzle(pool, { schema: { users, posts } }); async function runSeed() { try { console.log('Starting database reset...'); // Clears all specified tables, respecting foreign key constraints. await reset(db, { users, posts }); console.log('Database reset complete.'); console.log('Starting database seeding...'); await seed(db, { users, posts }).refine((f) => ({ users: { count: 5, // Create 5 users columns: { name: () => f.fullName(), email: () => f.email(), age: () => f.number.int({ min: 18, max: 80 }), }, with: { posts: 3, // Each user gets 3 posts }, }, posts: { columns: { title: () => f.lorem.sentence(), content: () => f.lorem.paragraph(), }, }, })); console.log('Database seeding complete.'); } catch (error) { console.error('Seeding failed:', error); process.exit(1); } finally { await pool.end(); process.exit(0); } } runSeed();

Debug

Known issues

breakingOlder versions of `drizzle-seed` (prior to 0.3.0) did not correctly synchronize PostgreSQL serial sequences after seeding. This could lead to `duplicate key value violates unique constraint` errors when inserting new records after a seed operation.

fix

Upgrade to `drizzle-seed@0.3.0` or higher. If upgrading is not immediately possible, a manual workaround is to run `SELECT setval('your_table_id_seq', (SELECT MAX(id) FROM your_table));` after seeding to update the sequence.

affects: <0.3.0

gotchaWhen using Drizzle ORM's casing configuration (e.g., `snake_case`), `drizzle-seed` might not correctly apply this casing to column names during insertion. This can lead to `column "columnName" does not exist` errors if the schema definition uses a different casing than the actual database.

fix

Ensure that your Drizzle schema column definitions match the actual casing in your database when using `drizzle-seed`, or manually specify column names in `refine` to align with the database's expected casing. This issue can be subtle as `drizzle-orm` itself handles casing, but `drizzle-seed` has had reports of not respecting it.

affects: >=0.3.0

gotcha`drizzle-seed` is a library, not a standalone executable. Attempting to run it directly via `npx drizzle-seed` will result in an error indicating it cannot determine an executable. Seed scripts must be run via Node.js (or `tsx`/`bun`/`deno` for TypeScript files).

fix

Execute your seed script directly using `node your-seed-script.js`, `ts-node your-seed-script.ts`, or similar runtime commands. For example: `bun run ./src/db/seed.ts`.

affects: >=0.1.0

breaking`drizzle-seed` has a peer dependency on `drizzle-orm` version `>=0.36.4`. Using older versions of `drizzle-orm` may lead to type mismatches, runtime errors related to identity columns, or other unexpected behavior due to API changes.

fix

Ensure `drizzle-orm` is updated to version `0.36.4` or higher in your project dependencies.

affects: <0.3.0

gotchaSeeding tables with foreign key relationships requires careful setup. If a foreign key column has a `not-null` constraint and the referenced table is not exposed to the `seed` function or the column generator is not refined, `drizzle-seed` cannot populate the column, leading to errors. TypeScript limitations can also hinder proper inference of relations, especially with circular dependencies.

fix

Always include all related tables in the schema argument of the `seed` function. Ensure `not-null` foreign key columns are either populated by `with` for related entities or have an explicit generator defined in `refine`. For complex or circular relations, manually provide `references` definitions in your Drizzle schema.

affects: >=0.1.0

Errors

Common errors & fixes

PostgresError: column "userTable" does not exist

Drizzle-seed attempted to insert data with a column name from the Drizzle schema that does not match the actual database column name, often due to casing configuration mismatches (e.g., camelCase in schema vs. snake_case in DB).

fix

Verify your `drizzle.config.ts` casing settings and ensure your Drizzle schema column names precisely match the database, or explicitly define column names in the `refine` callback of `drizzle-seed` to override.

duplicate key value violates unique constraint "users_pkey"

After seeding a table with a `serial` primary key, the PostgreSQL sequence generator was not updated, causing subsequent inserts to attempt to use an already existing ID.

fix

Upgrade `drizzle-seed` to version 0.3.0 or newer. As a temporary workaround for older versions, manually reset the sequence after seeding: `await db.execute(sql`SELECT setval('users_id_seq', (SELECT MAX(id) FROM users));`);`.

npm error could not determine executable to run

`drizzle-seed` is a library, not a CLI tool. This error occurs when trying to execute it directly via `npx`.

fix

Run your TypeScript seed file directly using a runtime like `ts-node`, `bun`, or `node` (after transpilation). Example: `ts-node src/seed.ts`.

Error: "posts" table doesn't have a reference to "users" table or you didn't include your one-to-many relation in the seed function schema. You can't specify "posts" as parameter in users.with object.

Attempting to use the `with` option for related entities in `drizzle-seed` when the foreign key relationship is not correctly defined in the Drizzle schema, or the related tables are not all passed to the `seed` function.

fix

Ensure all tables involved in a `with` relationship are included in the schema argument of the `seed` function, and that explicit foreign key `references` are correctly defined in your Drizzle schema (e.g., `userId: integer('user_id').references(() => users.id)`).

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

drizzle-ormrequiredCore ORM functionality is required for schema definition and database interaction.

Agent activity

13 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/drizzle-team/drizzle-orm ↗

packagehttps://www.npmjs.com/package/drizzle-seed ↗