@seedwise/core

Smart database seeding with run-once tracking. Seeds run like migrations — tracked, idempotent, and predictable.

Why Seedwise?

Traditional seeders run every time, causing duplicate data headaches. Seedwise tracks what's run in a _seedwise_history table — seeds execute once and never again (unless you want them to).

Installation

npm install @seedwise/core @seedwise/knex

Quick Start

1. Create config file (seedwise.config.ts):

import type { SeedwiseConfig } from '@seedwise/core';

const config: SeedwiseConfig = {
  adapter: 'knex',
  connection: './knexfile.ts',
  seedsDir: './seeds',
};

export default config;

2. Create a seed (seeds/001_users.ts):

import type { Knex } from 'knex';
import type { SeedConfig } from '@seedwise/core';

export const config: SeedConfig = {
  mode: 'once',  // Run once, tracked forever
  description: 'Seed initial admin user',
};

export async function seed(knex: Knex): Promise<void> {
  await knex('users').insert({
    email: '[email protected]',
    role: 'admin',
  });
}

3. Run seeds:

npx seedwise run

Seed Modes

| Mode | Behavior | |------|----------| | once | Run one time ever (default) | | always | Run on every seedwise run | | changed | Re-run if file content changes | | manual | Only run with --force or --name |

CLI Commands

seedwise run              # Run pending seeds
seedwise run --dry-run    # Preview what would run
seedwise run --name users # Run specific seed
seedwise status           # Show seed history
seedwise reset            # Clear history (re-run all)
seedwise reset --name X   # Reset specific seed
seedwise unlock           # Force-release stale lock

Configuration Options

All options are optional with sensible defaults:

interface SeedwiseConfig {
  adapter?: string;           // 'knex' (default)
  connection?: string;        // './knexfile.js'
  seedsDir?: string;          // './seeds'
  historyTable?: string;      // '_seedwise_history'
  lockTable?: string;         // '_seedwise_lock'
  timeout?: number;           // 30000 (ms)
  lockTimeout?: number;       // 60000 (ms)
  extensions?: string[];      // ['.js', '.ts']
  sortBy?: 'filename' | 'dependency';
  allowedEnvironments?: string[];
  verbose?: boolean;
}

Seed Configuration

export const config: SeedConfig = {
  mode: 'once',
  description: 'What this seed does',
  environments: ['development', 'staging'],  // Only run in these
  excludeEnvironments: ['production'],       // Never run in these
  dependsOn: ['001_roles'],                  // Run after these seeds
  tags: ['auth', 'critical'],                // Filter with --tag
  transaction: true,                         // Wrap in transaction
  timeout: 60000,                            // Custom timeout
};

Programmatic Usage

import { Seedwise } from '@seedwise/core';
import { KnexAdapter } from '@seedwise/knex';
import Knex from 'knex';

const knex = Knex(config);
const adapter = new KnexAdapter(knex);
const seedwise = new Seedwise({ adapter, seedsDir: './seeds' });

await seedwise.run();
await seedwise.status();
await seedwise.reset();

License

MIT