next-model-migrations-generator

name	next-model-migrations-generator
description	CLI and library (`@next-model/migrations-generator`, `nm-generate-migration`) that scaffolds timestamped migration files for `@next-model/migrations` and reflects a live database into a typed `defineSchema(...)` file via the `schema-from-db` subcommand. Trigger on requests like "scaffold a migration", "generate migration file", "create migration stub", or "reflect schema from a live db".
license	MIT
metadata	{"author":"tamino-martinius","version":"1.0.0"}

Overview

@next-model/migrations-generator is both a CLI (nm-generate-migration) and a programmatic library that scaffolds timestamped migration files for @next-model/migrations. It writes empty stubs, full createTable bodies with typed columns, dependency-graph parents, and — through the schema-from-db subcommand — reflects a live connector's schema into a typed defineSchema(...) TypeScript file so existing databases can be adopted into @next-model/core without re-stating every column shape by hand.

When to use

• Creating a new migration for @next-model/migrations (empty stub, createTable body, or with explicit parents for the dependency-graph runner).
• Introspecting an existing database into TypeScript defineSchema(...) declarations when adopting @next-model/core on a project that already has tables.

Install

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

Invoke through your package manager:

pnpm exec nm-generate-migration "add FK on posts"
# or
npx nm-generate-migration "add FK on posts"

CLI

The binary exposes two surfaces: the default migration scaffolder and the schema-from-db subcommand.

Default — scaffold a migration

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) for the dependency-graph runner:

pnpm exec nm-generate-migration "grant perms" \
  --parent 20250101000000000 \
  --parent 20250505000000000

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

schema-from-db — reflect a live database

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

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).

schema-from-db

The connector module passed to --connector must export a Connector instance — as the default export, 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 },
  },
});

The connector must implement reflectSchema(). Current support:

• @next-model/sqlite-connector ships with it.
• Native Postgres / MySQL / MariaDB / Aurora ship in follow-up releases.
• @next-model/memory-connector, @next-model/redis-connector, @next-model/valkey-connector, and @next-model/mongodb-connector leave reflectSchema undefined by design — the CLI exits with a helpful error if pointed at them.

Programmatic API

Scaffold or write a migration in code:

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.

Reflect a schema from a connector:

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
});

File layout

• Files are written to ./migrations by default; override with --dir <path> (or the directory option in writeMigration).
• Naming convention: <timestamp>_<slug>.ts, where the timestamp is UTC, millisecond-resolution (yyyymmddhhmmssxxx). This makes files sort chronologically and avoids collisions when several are generated in a row.
• Each generated file imports Connector from @next-model/core (override with --core-spec <module>) and exports a migration object with version, optional parents, and up / down bodies. With --create-table, the up body contains a createTable call populated from the column specs (plus default createdAt / updatedAt unless --no-timestamps); the down body drops the table.
• schema-from-db writes a single TypeScript file at --output, containing one export const <table>Schema = defineSchema({...}) per reflected table and a header comment marking it as generated.

See also

• next-model-migrations — the runtime that consumes the files this generator emits.
• next-model-core — defines Connector, defineSchema, and the column types referenced above.
• next-model-sqlite-connector — currently the only connector with reflectSchema() for schema-from-db.
• next-model-postgres-connector, next-model-mysql-connector, next-model-mariadb-connector, next-model-aurora-data-api-connector — native reflectSchema shipping in follow-up releases.
• next-model-memory-connector, next-model-redis-connector, next-model-valkey-connector, next-model-mongodb-connector — do not implement reflectSchema by design.