populate

What it does

Runs one or more populator files against your database. Populators are TypeScript files that seed data. Useful for local development, test setup, or resetting to a known state.

Run

npx damian populate
npx damian populate --group core
npx damian populate --group core --populator users

pnpm damian populate
pnpm damian populate --group core
pnpm damian populate --group core --populator users

yarn damian populate
yarn damian populate --group core
yarn damian populate --group core --populator users

Flags

Without flags, prompts you to select a group, then multi-select populators within it.

File structure

Place populator files under {root}/populators/{group}/ named *.populator.ts:

damian/
  populators/
    core/
      users.populator.ts
      roles.populator.ts
    sandbox/
      empty-state.populator.ts
      with-orders.populator.ts

Each file exports a default populator() instance:

import { populator } from 'damian'
import { db, sql } from '../../../src/db'

export default populator({
    populate: async () => {
        await db.query(sql.void`INSERT INTO public.users (name) VALUES ('Alice'), ('Bob')`)
    }
})

Dependencies

Use dependsOn to declare execution order. The runner topologically sorts so dependencies run first:

import { populator } from 'damian'

export default populator({
    dependsOn: ['users'],
    populate: async () => {
        // users guaranteed to exist
    }
})

Entries match base filenames without .populator.ts. All entries must exist in the same selected set.

Special groups

core and sandbox have special meaning in the sandbox command:

• core runs automatically before any sandbox populator
• sandbox represents different development scenarios; sandbox command asks you to pick one

The populate command treats all groups equally.