CLI

Schema lifecycle management and related tasks

The jsorm binary handles project initialization, SQL generation, health checks, and migration orchestration.

jsorm help

Initialization

Bootstrap a new project with the interactive wizard:

pnpm dlx jsorm@latest init
npx jsorm@latest init

jsorm init:

1. Prompts for schema entry path (default src/schema/index.ts)
2. Generates a deterministic schema structure with an example User model
3. Prompts for adapter(s) — installs packages and peer drivers
4. Provisions the Rust engine binary into node_modules/.jsorm/engine
5. Writes jsorm.config.ts with connection and migration sources
6. Creates .env with a DATABASE_URL placeholder if missing

Tip

Run jsorm init once per project. The generated jsorm.config.ts is shared by the runtime singleton and all CLI commands.

Config-first mode

When jsorm.config.ts has defaults configured, CLI commands need no arguments:

jsorm db:check              # verify adapter connectivity
jsorm migrate:status        # check pending migrations
jsorm migrate               # apply all pending migrations
jsorm migrate:up            # apply next pending migration
jsorm migrate:down          # roll back last batch (guarded in prod)
jsorm table:create          # generate DDL for default model
jsorm table:create User     # generate DDL for named model
jsorm migrate:statement     # generate SQL for default migration
jsorm migrate:statement initUsers  # generate SQL for named migration
jsorm migrate:generate      # diff models vs snapshot, emit migration file

Legacy module-export mode

Pass the compiled JS file and export name when not using config-first:

jsorm migrate ./dist/schema.js ormSource
jsorm migrate:up ./dist/schema.js ormSource
jsorm migrate:down ./dist/schema.js ormSource
jsorm migrate:status ./dist/schema.js ormSource
jsorm db:check ./dist/schema.js connectionSource
jsorm table:create ./dist/schema.js User
jsorm migrate:statement ./dist/schema.js initUsers
jsorm migrate:generate ./dist/schema.js generateSource

Compile TypeScript before running legacy commands:

tsc && jsorm migrate:status ./dist/schema.js ormSource

Environment safety matrix

Command	Safe in production	Notes
migrate	✅ Yes	Applies pending only
migrate:up	✅ Yes	One step at a time
migrate:status	✅ Yes	Read-only
db:check	✅ Yes	Read-only
migrate:down	⚠️ Guarded	Requires JSORM_ALLOW_UNSAFE_OPERATIONS=true
db:fresh	❌ Blocked	Development only
db:rollback	❌ Blocked	Development only

Caution

db:fresh and db:rollback are hard-blocked in production even with the env override. Never automate them in production CI.

Automatic migration generation

migrate:generate diffs your current model definitions against the stored schema snapshot and emits a reviewed migration file:

jsorm migrate:generate

Flow:

1. Reads current models from config
2. Loads .migrations/schema.json snapshot
3. Builds an AST diff
4. Classifies each change as safe, review_required, or dangerous
5. Emits .migrations/<timestamp>_<tables>.ts
6. Review and edit the file before applying with jsorm migrate

Tip

migrate:generate also logs detected implicit many-to-many relationships, including inferred pivot table and foreign-key names.

Engine binary

The CLI requires the Rust engine binary. If it’s missing, the CLI stops with an explicit error:

[JSORM ENGINE MISSING] Run: pnpx jsorm init

Use JSORM_ENGINE_PATH to point at an explicit binary path in containerized or CI environments.

Debug mode

JSORM_DEBUG=1 jsorm migrate:status

Logs: config loading, engine binary path resolution, adapter initialization, and query dispatch.

Best practices

1. Use pnpm dlx jsorm@latest init to set up new projects — it wires engine + config correctly.
2. Use db:check in CI deploy verification to confirm adapter connectivity.
3. Keep destructive commands (db:fresh, db:rollback) out of production automation.
4. Run migrate:status as part of deployment to confirm all migrations applied.
5. Use migrate:up (one step) for cautious incremental rollouts.