🌱 Data Seeding Strategies

What Is Seeding?

Data seeding is the process of populating a database with an initial set of records. Where migrations evolve the structure, seeds provide the starting content — the data your app needs to be usable, testable, or demonstrable. Together they form a complete database setup: migrate to build, seed to fill.

Types of Seed Data

Not all seed data serves the same purpose, and mixing the categories up is how test users end up in a production database. Learn the four kinds.

Idempotency & Environment Guards

Two properties separate professional seeds from scripts that corrupt a database on the second run.

Idempotent = safe to re-run

An idempotent seed produces the same result no matter how many times you run it — no duplicate rows, no unique-constraint crashes. The simplest way to achieve this with Knex is to clear the table before inserting, so a re-run replaces rather than accumulates:

exports.seed = async function (knex) {
  await knex('roles').del();          // clear first...
  await knex('roles').insert([        // ...then insert a known set
    { id: 1, name: 'user' },
    { id: 2, name: 'admin' },
  ]);
};

For reference data that other tables point to, a delete-then-insert can trip foreign keys. There, prefer an upsert — insert, and on a conflicting key, update instead:

// PostgreSQL upsert via Knex: idempotent without deleting referenced rows
exports.seed = async function (knex) {
  await knex('roles')
    .insert([
      { id: 1, name: 'user' },
      { id: 2, name: 'admin' },
    ])
    .onConflict('id')   // if the id already exists...
    .merge();           // ...update the row instead of erroring
};

Environment guards

The second property: a seed must know where it is. Development seeds should refuse to run in production. A one-line guard does it:

exports.seed = async function (knex) {
  // Never insert bulk fake data into production.
  if (process.env.NODE_ENV === 'production') {
    console.log('Skipping development seed in production.');
    return;
  }
  // ...generate development data below
};

Seeding with Knex

Knex's seed system mirrors its migrations. Create a seed file, and Knex drops it into the seeds directory from your knexfile.js.

npx knex seed:make 01_reference_data
npx knex seed:make 02_dev_users

# Run all seeds (alphabetical order — hence the number prefixes)
npx knex seed:run

# Run just one
npx knex seed:run --specific=01_reference_data.js

Ordering matters

Knex runs seeds in alphabetical order, so number your files to control dependencies — seed the tables that others reference first:

• 01_reference_data.js — roles, categories, statuses
• 02_users.js — needs roles to exist
• 03_products.js — needs categories and users
• 04_orders.js — needs users and products

Reference data seed

// db/seeds/01_reference_data.js
// Reference data: runs in EVERY environment, including production.
exports.seed = async function (knex) {
  await knex('order_statuses')
    .insert([
      { id: 1, code: 'pending',   name: 'Pending' },
      { id: 2, code: 'shipped',   name: 'Shipped' },
      { id: 3, code: 'delivered', name: 'Delivered' },
      { id: 4, code: 'cancelled', name: 'Cancelled' },
    ])
    .onConflict('id')
    .merge(); // idempotent, and safe for rows referenced by orders
};

Development seed with password hashing

Development data can be destructive (delete-then-insert) because it's disposable — but it still needs an environment guard and should hash passwords rather than storing them in plain text:

// db/seeds/02_dev_users.js
const bcrypt = require('bcrypt');

exports.seed = async function (knex) {
  if (process.env.NODE_ENV === 'production') return; // guard

  await knex('users').del();

  const hash = (pw) => bcrypt.hash(pw, 10); // never store raw passwords

  await knex('users').insert([
    {
      username: 'admin',
      email: 'admin@example.com',
      password_hash: await hash('admin123'),
      is_admin: true,
    },
    {
      username: 'demo',
      email: 'demo@example.com',
      password_hash: await hash('demo123'),
      is_admin: false,
    },
  ]);
};

Realistic Data with Faker.js

Hand-typing fifty users is tedious and produces obviously fake data. Faker.js generates realistic names, emails, addresses, prices, and more — perfect for filling a development database with data that actually exercises your UI and business logic.

npm install @faker-js/faker

// db/seeds/03_dev_products.js
const { faker } = require('@faker-js/faker');

exports.seed = async function (knex) {
  if (process.env.NODE_ENV === 'production') return; // guard

  await knex('products').del();

  const products = [];
  for (let i = 0; i < 100; i++) {
    products.push({
      name: faker.commerce.productName(),
      description: faker.commerce.productDescription(),
      price: parseFloat(faker.commerce.price({ min: 10, max: 1000 })),
      category_id: faker.number.int({ min: 1, max: 5 }),
      created_at: faker.date.past(),
    });
  }

  // batchInsert splits a large array into chunks — far faster than
  // 100 individual INSERTs, and avoids hitting parameter limits.
  await knex.batchInsert('products', products, 25);
};

Generating related data

Realistic seeds respect relationships. To create orders, first read the real IDs that already exist, then reference them — never invent foreign keys and hope they line up:

// db/seeds/04_dev_orders.js
const { faker } = require('@faker-js/faker');

exports.seed = async function (knex) {
  if (process.env.NODE_ENV === 'production') return;

  await knex('orders').del();

  // Pull IDs that actually exist so foreign keys are valid.
  const users = await knex('users').select('id');
  const products = await knex('products').select('id', 'price');

  const orders = [];
  for (let i = 0; i < 200; i++) {
    const user = faker.helpers.arrayElement(users);
    const picked = faker.helpers.arrayElements(
      products,
      faker.number.int({ min: 1, max: 5 })
    );
    const total = picked.reduce((sum, p) => sum + parseFloat(p.price), 0);

    orders.push({
      user_id: user.id,
      status_id: faker.number.int({ min: 1, max: 4 }),
      total_amount: parseFloat(total.toFixed(2)),
      shipping_city: faker.location.city(),
      created_at: faker.date.past(),
    });
  }

  await knex.batchInsert('orders', orders, 50);
};

Handy Faker generators

Seeding in CI/CD

Seeding shines when it's automated. In CI, a fresh database is migrated and seeded with predictable test data before the suite runs; in production, only reference data is seeded, once.

Per-environment npm scripts

// package.json
{
  "scripts": {
    "migrate:test": "knex migrate:latest --env test",
    "seed:test":    "knex seed:run --env test",
    "setup:test":   "npm run migrate:test && npm run seed:test",

    "seed:dev":     "knex seed:run --env development",
    "seed:prod":    "knex seed:run --env production --specific=01_reference_data.js"
  }
}

Note the production script: it runs only the reference-data seed via --specific, never the development or Faker seeds. That's the environment guard reinforced at the command level.

A GitHub Actions test job

# .github/workflows/test.yml (excerpt)
- name: Run migrations
  run: npm run migrate:test

- name: Seed test database
  run: npm run seed:test

- name: Run tests
  run: npm test
  env:
    NODE_ENV: test

Practice & Quiz

exports.seed = async function (knex) {
  await knex('categories').insert([
    { id: 1, name: 'Electronics', slug: 'electronics' },
    { id: 2, name: 'Books', slug: 'books' },
  ]);
};

exports.seed = async function (knex) {
  await knex('categories')
    .insert([
      { id: 1, name: 'Electronics', slug: 'electronics' },
      { id: 2, name: 'Books', slug: 'books' },
    ])
    .onConflict('id')  // row already there?
    .merge();          // update it — no duplicate, no crash, no deletion
};

const { faker } = require('@faker-js/faker');

exports.seed = async function (knex) {
  if (process.env.NODE_ENV === 'production') return;

  await knex('users').del();

  const users = [];
  for (let i = 0; i < 50; i++) {
    const firstName = faker.person.firstName();
    const lastName = faker.person.lastName();
    users.push({
      username: faker.internet.username({ firstName, lastName }),
      email: faker.internet.email({ firstName, lastName }),
      password_hash: 'seed-placeholder-hash', // replace with a real bcrypt hash
      is_admin: false,
    });
  }

  await knex.batchInsert('users', users, 25);
};

Best Practices & Pitfalls

✅ Do

• Keep seed files in version control alongside your migrations
• Make every seed idempotent (delete-then-insert for disposable data, upsert for referenced data)
• Guard development/test seeds with a NODE_ENV check
• Separate reference seeds from development/test seeds into different files
• Order seed files (number prefixes) so foreign-key dependencies are satisfied
• Use batchInsert for large volumes; parameterize the count so you can generate more or less
• Read existing IDs before referencing them in generated data

❌ Don't

• Never run development or Faker seeds against production
• Don't hard-code IDs that might collide across environments (except stable reference rows)
• Don't store plain-text passwords, even in seeds — hash them
• Don't insert thousands of rows one at a time
• Don't seed data whose foreign keys point at rows that don't exist yet
• Don't over-seed — bloated development data slows everyone down

Summary

📚 Additional Resources

• Knex.js — Seed files documentation
• Faker.js — official guide
• Prisma — database seeding
• Martin Fowler — Test Data Builder pattern

🚀 What's Next?

You've now covered the full database lifecycle — connect, model, query, relate, migrate, and seed. Time to put it all together: the next lesson is a hands-on weekend project building a complete Blog API with database integration, migrations and seeds included.