Deploy

Flujo de deploy en producción

Usa jsorm deploy como entrypoint seguro de migraciones para producción. Mantén separado el runtime de requests de la propiedad del schema y ejecuta los deploys desde un entorno Node.js controlado.

Quién es dueño del deploy

Paquete/runtime	Úsalo para	No lo uses para
@jsorm/runtime + @jsorm/fetch	Handlers edge-safe y acceso SQL vía fetch	Ser dueño de migraciones o jsorm deploy
@jsorm/core / @jsorm/node + adaptadores nativos	Servicios Node, release jobs, acceso directo a base de datos	Edge isolates sin soporte TCP/binarios nativos
@jsorm/node	CLI, migraciones, jsorm deploy, automatización de releases	Manejar requests edge

jsorm deploy es intencionalmente de propiedad Node-only. Aunque la app corra en Vercel Edge o Cloudflare Workers, el deploy debe ejecutarse en CI, un release job o un contenedor dedicado con @jsorm/node.

Consejo

Para apps edge, deja las queries runtime en @jsorm/runtime + @jsorm/fetch, pero deja las migraciones y la verificación de deploy en @jsorm/node.

Qué hace jsorm deploy

jsorm deploy [selector] [--dry-run] [--verbose] [--strict] [--force]

jsorm deploy:

1. valida conectividad
2. revisa hashes/checksums de migraciones aplicadas
3. inspecciona migraciones pendientes por cambios inseguros
4. verifica integridad del snapshot antes de ejecutar
5. aplica migraciones pendientes, o solo las previsualiza con --dry-run
6. vuelve a verificar el snapshot después de ejecutar

Cuando jsorm.config.ts define un migration source por defecto, el selector es opcional:

pnpm exec jsorm deploy --strict --verbose
pnpm exec jsorm deploy main --strict

Flags

Flag	Significado	Uso típico
--dry-run	Previsualiza el plan pendiente sin mutar el historial de migraciones	Validación en CI y revisión previa
--verbose	Imprime issues y sentencias SQL compiladas	Logs de release y troubleshooting
--strict	Falla con warnings, drift del snapshot o cambios que requieren revisión	Valor por defecto en CI y producción
--force	Permite migraciones destructivas bloqueadas por defecto	Solo tras revisión explícita

Exit codes e intención para CI

jsorm deploy está pensado para decisiones de CI/CD:

Exit code	Significado	Interpretación en CI
0	Éxito	Promover release
2	Error de uso/CLI	Corregir comando o config
3	Falla de conectividad/preflight	Reintentar infraestructura o secretos
4	Falla de integridad	Frenar release e investigar drift/checksums
5	Deploy inseguro bloqueado	Requiere revisión o --force
6	Falla de ejecución/verificación	Frenar rollout e inspeccionar estado de la base

Comandos recomendados:

# preview en CI
pnpm exec jsorm deploy --dry-run --strict --verbose

# release de producción
pnpm exec jsorm deploy --strict --verbose

Flujo recomendado en producción

1. Construye artefactos.
2. Ejecuta jsorm deploy --dry-run --strict --verbose en CI.
3. Ejecuta jsorm deploy --strict --verbose en el release job.
4. Solo entonces promociona la nueva versión de la app.

Así mantienes la propiedad del schema en Node, el bundle edge minimalista y señales explícitas de fallo para CI.

Ejemplos de deploy

GitHub Actions

name: deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 11
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm run build
      - run: pnpm exec jsorm deploy --strict --verbose
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}

Vercel

• Runtime Node: usa @jsorm/core o @jsorm/node con adaptadores nativos y fija handlers cuando haga falta:

export const runtime = 'nodejs';

• Runtime Edge: usa @jsorm/runtime + @jsorm/fetch en el bundle.
• Ejecuta pnpm exec jsorm deploy --strict --verbose en GitHub Actions u otro release step Node, no dentro de la función edge.

Cloudflare Workers

• Usa @jsorm/runtime + @jsorm/fetch para el acceso en request-time.
• Ejecuta el deploy aparte desde un job Node antes de publicar el Worker.

pnpm exec jsorm deploy --strict --verbose
pnpm exec wrangler deploy

Docker

Ejecuta el deploy antes de arrancar la app, o muévelo a un init container one-off:

FROM node:24-alpine AS build
WORKDIR /app
COPY . .
RUN corepack enable && pnpm install --frozen-lockfile && pnpm run build

FROM node:24-alpine
WORKDIR /app
COPY --from=build /app ./
RUN corepack enable
CMD ["sh", "-c", "pnpm exec jsorm deploy --strict --verbose && pnpm start"]

Supabase

Usa un deploy job Node con @jsorm/pg contra la conexión Postgres:

pnpm exec jsorm deploy main --strict --verbose

Si el runtime de la app es solo edge, deja el tráfico runtime en @jsorm/runtime + @jsorm/fetch, pero mantén el deploy en Node.

Neon

• Deploy/migraciones: job Node + @jsorm/pg
• Path de requests edge: @jsorm/runtime + @jsorm/fetch cuando expongas acceso SQL por HTTP

pnpm exec jsorm deploy --strict --verbose

PlanetScale

Usa un deploy job Node con @jsorm/mysql:

pnpm exec jsorm deploy main --strict --verbose

Para tráfico runtime edge, mantén un path HTTP/fetch separado. No esperes que el adaptador MySQL nativo funcione dentro de edge isolates.