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.