@next-model/migrations-generator

Scaffolds @next-model/migrations files — CLI + programmatic API.

pnpm add -D @next-model/migrations-generator
# or: npm install -D @next-model/migrations-generator

CLI

# Empty stub
pnpm exec nm-generate-migration "add FK on posts"

# Full createTable body with columns
pnpm exec nm-generate-migration "create users" \
  --create-table users \
  --column id:integer:primary:autoIncrement:not-null \
  --column name:string:not-null \
  --column age:integer

# Declare the migration's parent(s) — works with the dependency-graph runner
pnpm exec nm-generate-migration "grant perms" \
  --parent 20250101000000000 \
  --parent 20250505000000000

Resulting file lives in ./migrations/<timestamp>_<slug>.ts (override with --dir). The filename timestamp is UTC, millisecond-resolution (yyyymmddhhmmssxxx) so files sort chronologically and don't collide when you generate several in a row.

Column spec grammar

name[:type[:flag...]]

• type: integer | bigint | float | string | text | boolean | date | datetime | json (defaults to string; unknown kinds fall back to string)
• flags: primary, autoIncrement, nullable (explicit null: true), not-null (explicit null: false)

Flag reference

| Flag | Effect | |--------------------------------|---------------------------------------------------------------------| | --dir <path> | Output directory (default: ./migrations) | | --create-table <name> | Scaffold a createTable body for <name> | | --column <spec> | Column spec for --create-table, repeatable | | --no-timestamps | Omit default createdAt + updatedAt columns | | --parent <version> | Parent migration version (repeatable) | | --version <string> | Override the auto-generated version | | --core-spec <module> | Import specifier for Connector (default: @next-model/core) | | --require-existing-dir | Fail instead of creating the output directory |

Programmatic API

import { generateMigration, writeMigration } from '@next-model/migrations-generator';

const { contents, fileName, version } = generateMigration({
  name: 'create users',
  createTable: { tableName: 'users' },
});

writeMigration({
  name: 'create users',
  directory: './db/migrations',
  createTable: { tableName: 'users' },
});

writeMigration refuses to overwrite an existing file (uses { flag: 'wx' }), so re-runs are safe as long as clocks move forward.

Reflecting a live database (schema-from-db)

Generate defineSchema(...) declarations from a database that already exists. Useful for adopting @next-model/core on an existing project without re-stating every column shape by hand.

pnpm exec nm-generate-migration schema-from-db \
  --connector ./db-connector.js \
  --output ./src/generated/schema.ts

The connector module must export a Connector instance (default export, or named connector, or a default factory). The CLI calls connector.reflectSchema() and writes the same output the migrator's schemaOutputPath produces:

// Generated by @next-model/migrations — do not edit by hand.

import { defineSchema } from '@next-model/core';

export const usersSchema = defineSchema({
  tableName: 'users',
  columns: {
    id: { type: 'integer', primary: true, autoIncrement: true },
    email: { type: 'string', unique: true, limit: 320 },
  },
});

Pass --import-path '@my/core-alias' to override the defineSchema import specifier in the generated file (matches the --core-spec flag for the migration scaffolder).

The connector must implement reflectSchema() — currently @next-model/sqlite-connector ships with it; native Postgres / MySQL / MariaDB / Aurora ship in follow-up releases. Memory / Redis / Valkey / Mongo connectors leave reflectSchema undefined by design and the CLI exits with a helpful error if you point it at one.

Programmatic API

import { runSchemaFromDb } from '@next-model/migrations-generator';

const { tables, path } = await runSchemaFromDb({
  connector: './db-connector.js',
  output: './src/schema.ts',
  importPath: '@next-model/core',  // optional
});