Deployment

Production deploy workflow

Use jsorm deploy as the production-safe migration entrypoint. Keep request-time runtime code separate from schema ownership, and run deploys from a controlled Node.js environment.

Deployment ownership

| Package/runtime | Use it for | Do not use it for | |-----------------|------------|-------------------| | @jsorm/runtime + @jsorm/fetch | Edge-safe request handlers and fetch-based SQL access | Owning migrations or jsorm deploy | | @jsorm/core / @jsorm/node + native adapters | Node services, release jobs, direct database access | Edge isolates without TCP/native binary support | | @jsorm/node | CLI, migrations, jsorm deploy, release automation | Edge request handling |

jsorm deploy is intentionally Node-only deployment ownership. Even if the app runs on Vercel Edge or Cloudflare Workers, deploys should run in CI, a release job, or a dedicated container with @jsorm/node.

Tip

For edge apps, keep runtime queries on @jsorm/runtime + @jsorm/fetch, but keep migrations and deploy verification on @jsorm/node.

What jsorm deploy does

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

jsorm deploy:

1. validates connectivity
2. checks applied migration hashes/checksums
3. inspects pending migrations for unsafe changes
4. verifies schema snapshot integrity before execution
5. applies pending migrations, or previews them with --dry-run
6. verifies schema snapshot integrity again after execution

When jsorm.config.ts defines a default migration source, selector mode is optional:

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

Flags

| Flag | Meaning | Typical use | |------|---------|-------------| | --dry-run | Preview pending deploy plan without mutating migration history | CI validation and pre-release review | | --verbose | Print issues and compiled SQL statements | Release logs and troubleshooting | | --strict | Fail on warnings, snapshot drift, or review-required changes | Default for CI and production | | --force | Allow destructive migrations that are blocked by default | Only after explicit review |

Exit codes and CI intent

jsorm deploy is designed for CI/CD decisions:

| Exit code | Meaning | CI interpretation | |-----------|---------|-------------------| | 0 | Success | Promote release | | 2 | Usage/CLI error | Fix command/config | | 3 | Connectivity/preflight failure | Retry infra or secrets setup | | 4 | Integrity failure | Stop release and investigate drift/checksums | | 5 | Unsafe deploy blocked | Require review or --force | | 6 | Execution/verification failure | Stop rollout and inspect database state |

Recommended release commands:

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

# production release
pnpm exec jsorm deploy --strict --verbose

Recommended production flow

1. Build artifacts.
2. Run jsorm deploy --dry-run --strict --verbose in CI.
3. Run jsorm deploy --strict --verbose in the release job.
4. Only then promote the new app version.

This keeps migration ownership in Node, keeps edge bundles minimal, and gives CI explicit failure signals.

Deployment examples

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

• Node runtime: use @jsorm/core or @jsorm/node with native adapters and pin handlers when needed:

export const runtime = 'nodejs';

• Edge runtime: use @jsorm/runtime + @jsorm/fetch in the app bundle.
• Run pnpm exec jsorm deploy --strict --verbose in GitHub Actions or another Node release step, not inside the edge function.

Cloudflare Workers

• Use @jsorm/runtime + @jsorm/fetch for request-time access.
• Run deploy separately from a Node job before publishing the Worker.

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

Docker

Run deploy before app startup, or move it into a one-off init container:

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

Use a Node deploy job with @jsorm/pg against the Postgres connection string:

pnpm exec jsorm deploy main --strict --verbose

If the app runtime is edge-only, keep runtime traffic on @jsorm/runtime + @jsorm/fetch, but keep deploy on Node.

Neon

• Deploy/migrations: Node job + @jsorm/pg
• Edge request path: @jsorm/runtime + @jsorm/fetch when you expose HTTP SQL access

pnpm exec jsorm deploy --strict --verbose

PlanetScale

Use a Node deploy job with @jsorm/mysql:

pnpm exec jsorm deploy main --strict --verbose

For edge request traffic, keep a separate HTTP/fetch access path. Do not expect the native MySQL adapter to run inside edge isolates.