CLI

Ciclo de vida de schema y comandos operativos

El binario jsorm maneja inicialización, generación SQL, health checks y orquestación de migraciones.

jsorm help

Inicialización

Bootstrap de proyecto:

pnpm dlx @jsorm/core init
# o
npx -p @jsorm/core jsorm init

jsorm init ahora:

1. Detecta si src/schema/ existe — solo pregunta la ruta de schema si falta.
2. Genera archivos base de schema (solo si no existen).
3. Recorre setup de bases/adaptadores en bucle (puedes agregar múltiples bases). Si jsorm.config.ts ya existe, las conexiones existentes se fusionan.
4. Escribe jsorm.config.ts.
5. Genera helpers runtime (db.ts por defecto, jsormdb.ts fallback cuando aplica).
6. Verifica bootstrap y readiness de workers antes de finalizar.

Usa --no-migrations para omitir scaffolding de migraciones (sin .migrations/, sin config de migraciones).

Consejo

Los helpers runtime generados exportan funciones create*Jsorm() y start*Jsorm() para bootstrap explícito en la app.

Modo config-first

Cuando jsorm.config.ts define defaults, no necesitas argumentos extra:

jsorm db:check
jsorm migrate:status
jsorm migrate
jsorm migrate:up
jsorm migrate:down
jsorm table:create
jsorm table:create User
jsorm migrate:statement
jsorm migrate:statement initUsers
jsorm migrate:generate

Modo módulo-export (fallback legacy)

Si no usas 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

Compila primero:

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

Seguridad por entorno

| Comando | Seguro en producción | Notas | |---------|----------------------|-------| | migrate | ✅ Sí | Solo aplica pendientes | | migrate:up | ✅ Sí | Un paso por vez | | migrate:status | ✅ Sí | Solo lectura | | db:check | ✅ Sí | Solo lectura | | migrate:down | ⚠️ Protegido | Requiere JSORM_ALLOW_UNSAFE_OPERATIONS=true | | db:fresh | ❌ Bloqueado | Solo desarrollo | | db:rollback | ❌ Bloqueado | Solo desarrollo |

Precaución

db:fresh y db:rollback están bloqueados en producción. No los automatices en pipelines productivos.

migrate:generate

jsorm migrate:generate

Flujo:

1. Lee modelos desde config.
2. Carga .migrations/schema.json.
3. Construye diff AST.
4. Clasifica cambios (safe, review_required, dangerous).
5. Emite archivo de migración.
6. Revisa antes de aplicar.

Engine y debug

Si falta engine, la CLI se detiene con un mensaje accionable:

[JSORM ENGINE MISSING] Run: pnpx jsorm init

Usa ruta explícita en CI/contenedores:

JSORM_ENGINE_PATH=/ruta/jsorm-engine jsorm migrate:status

Modo debug:

JSORM_DEBUG=1 jsorm migrate:status

Buenas prácticas

1. Usa pnpm dlx @jsorm/core init en proyectos nuevos.
2. Mantén db:check en verificación de deploy.
3. Evita comandos destructivos en automatización de producción.
4. Ejecuta migrate:status durante deploys.
5. Prefiere arranque runtime explícito (start*Jsorm() o createJsorm().init()) en código de app.