Prisma Seeding Pattern

Seed databases idempotently with prisma/seed.ts, --seed flag, and environment branching

When to Use

• Populating a development database with test data after

  prisma migrate reset

• Setting up required reference data (roles, categories, config records)
• Creating reproducible test fixtures for integration tests
• Bootstrapping demo environments with sample data

Instructions

1. Create the seed file at

   prisma/seed.ts

   :

import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

async function main() {
  // Reference data — always needed
  const adminRole = await prisma.role.upsert({
    where: { name: 'ADMIN' },
    update: {},
    create: { name: 'ADMIN', permissions: ['read', 'write', 'delete'] },
  });

  // Development data — sample records
  const user = await prisma.user.upsert({
    where: { email: 'admin@example.com' },
    update: {},
    create: {
      email: 'admin@example.com',
      name: 'Admin User',
      roleId: adminRole.id,
    },
  });

  console.log({ adminRole, user });
}

main()
  .then(() => prisma.$disconnect())
  .catch(async (e) => {
    console.error(e);
    await prisma.$disconnect();
    process.exit(1);
  });

2. Configure the seed command in

   package.json

   :

{
  "prisma": {
    "seed": "tsx prisma/seed.ts"
  }
}

Use

tsx

or

ts-node

for TypeScript seeds. Ensure the runner is in

devDependencies

.

3. Make seeds idempotent — use

   upsert

   instead of

   create

   so the seed can run multiple times without duplicating data:

await prisma.category.upsert({
  where: { slug: 'technology' },
  update: { name: 'Technology' },
  create: { slug: 'technology', name: 'Technology' },
});

4. Branch by environment to seed different data for dev, staging, and testing:

async function main() {
  await seedReferenceData(); // Always runs

  if (process.env.NODE_ENV !== 'production') {
    await seedDevelopmentData(); // Sample users, posts, etc.
  }

  if (process.env.SEED_DEMO === 'true') {
    await seedDemoData(); // Curated demo content
  }
}

5. Run the seed manually:

npx prisma db seed

The seed also runs automatically after

prisma migrate reset

and

prisma migrate dev

(when a new migration is created).

6. Use factories for volume — when you need many records, use a helper function:

function createRandomUser() {
  return {
    email: `user-${crypto.randomUUID()}@example.com`,
    name: `User ${Math.random().toString(36).slice(2)}`,
  };
}

await prisma.user.createMany({
  data: Array.from({ length: 100 }, createRandomUser),
  skipDuplicates: true,
});

7. Seed in correct dependency order — create parent records before children. For circular dependencies, create records without relations first, then update with connections.

8. Reset and reseed in one command:

npx prisma migrate reset --force

This drops the database, applies all migrations, and runs the seed script.

Details

Prisma seeding runs as a standalone Node.js script invoked by the Prisma CLI. It has full access to Prisma Client and can include any business logic needed to set up the data.

Seed vs migration data: Reference data that must exist for the application to function (enum-like lookup tables, system config) belongs in migrations as

INSERT

statements, not in seeds. Seeds are for development convenience; migrations are for production correctness.

Performance for large seeds:

createMany

is significantly faster than individual

create

calls because it batches into a single

INSERT

with multiple value tuples. However,

createMany

does not support nested creates — use it for flat data and fall back to

create

for relational data.

Testing seeds: Create a separate seed function that returns the created data for use in integration tests:

export async function seedTestData(prisma: PrismaClient) {
  const user = await prisma.user.create({ data: { ... } });
  return { user };
}

Call this from your test setup with a transaction that rolls back after each test.

Common mistakes:

• Not disconnecting the client — the seed script hangs if

  prisma.$disconnect()

  is not called
• Using

  create

  instead of

  upsert

  — the seed fails on second run
• Hardcoding IDs — use

  cuid()

  or let the database auto-generate. Hardcoded IDs collide across environments
• Seeding production — guard with environment checks and never include

  prisma.seed

  configuration in production images

Source

https://prisma.io/docs/orm/prisma-migrate/workflows/seeding

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.