Drizzle Seed

Common errors

• PostgresError: column "userTable" does not exist

  cause 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"

  cause 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

  cause `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.

  cause 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)`).

Warnings

• breaking Older 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.
• gotcha When 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.
• 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`.
• 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.
• gotcha Seeding 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.

Install

• npm install drizzle-seed npm
• yarn add drizzle-seed yarn
• pnpm add drizzle-seed pnpm

Imports

• seed
  wrong:

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

  correct:

  import { seed } from 'drizzle-seed';

  The primary function for initiating the seeding process. Always a named import.
• reset
  wrong:

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

  correct:

  import { reset } from 'drizzle-seed';

  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.

Quickstart

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();