Damian

Damian runs your database migration, schema generation, seed, and shadow database commands from one damian.json file.

It ships no driver and requires no schema format. You choose the tools.

Why Damian

Many object-relational mappers (ORMs) generate SQL migrations from a TypeScript schema. This creates two sources of truth: the schema you wrote and the migration your database executes.

Damian reverses the flow:

1. Write the migration.
2. Apply it with your migration tool.
3. Replay it against a fresh shadow database when configured.
4. Generate the ORM schema from that database.

Migrations stay authoritative. Your database and generated schema derive from the same files.

Install

Use Node.js 22 or newer. Install Damian and your selected tools:

npm install --save-dev damian dbmate

Damian uses your platform’s default shell.

Configure

Create damian.json:

{
  "$schema": "./node_modules/damian/dist/damian.schema.json",
  "presets": {
    "migrate": "dbmate"
  }
}

Set your database URL in .env:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/app

Run a migration:

npx damian new --name create_users
npx damian up
npx damian status

Commands

| Command | Action | | --- | --- | | damian new | Create a migration | | damian migrate | Apply pending migrations | | damian up | Create or update the database | | damian rollback | Roll back a migration | | damian down | Alias for rollback | | damian reset | Recreate the database after confirmation | | damian status | Show migration status | | damian generate | Run up, then generate schema artifacts | | damian seed | Run selected seeds | | damian sandbox | Reset, migrate, generate, and seed |

All commands accept --config, --debug, and --dry-run. Seed dry-runs print hooks and runner commands without executing them.

Presets

Damian includes four presets:

| Section | Preset | Required command | | --- | --- | --- | | migrate | dbmate | dbmate | | generate | drizzle-kit | drizzle-kit | | shadow | pglite | pglite-server | | seed | typescript | tsx |

Use any combination:

{
  "presets": {
    "migrate": "dbmate",
    "generate": "drizzle-kit",
    "shadow": "pglite",
    "seed": "typescript"
  }
}

Install each command separately. Your config overrides preset values.

The Drizzle Kit preset runs drizzle-kit pull without changing the generated output.

Custom tools

Replace presets with shell commands:

{
  "migrate": {
    "commands": {
      "new": "my-migrator new {arg:--name,-n|Migration name}",
      "migrate": "my-migrator migrate",
      "up": "my-migrator up",
      "rollback": "my-migrator rollback",
      "reset": "my-migrator reset",
      "status": "my-migrator status"
    }
  },
  "generate": "my-generator pull"
}

Use --dry-run to inspect resolved commands. Unknown CLI flags reach a command only through an {arg:...} token.

Documentation

Read the Damian documentation for configuration fields, templates, generation, seeds, and troubleshooting.

License

MIT