Adaptadores

Adaptadores nativos vs fetch

jsorm mantiene el acceso a base de datos fuera del núcleo del ORM. Tú eliges el adaptador según dónde corre tu código:

• Adaptadores nativos (@jsorm/pg, @jsorm/mysql, @jsorm/sqlite) para runtimes Node/Bun con acceso directo a la base de datos.
• Adaptador fetch (@jsorm/fetch) para runtimes edge o fetch-only que no pueden abrir sockets TCP ni ejecutar binarios nativos.

Usa @jsorm/node para el CLI y para los flujos de deploy/migraciones en producción, incluso si tu app usa @jsorm/runtime + @jsorm/fetch.

Paquetes de adaptadores

| Paquete | Tipo | Mejor para | | --- | --- | --- | | @jsorm/pg | Adaptador nativo TCP | PostgreSQL en servicios Node, workers, CI y deploy jobs | | @jsorm/mysql | Adaptador nativo TCP | Targets MySQL como PlanetScale desde Node | | @jsorm/sqlite | Adaptador nativo in-process | Archivos SQLite locales, apps embebidas, tests y tooling | | @jsorm/fetch | Adaptador HTTP/fetch | Vercel Edge, Cloudflare Workers y otros runtimes fetch-only |

Matriz de compatibilidad por runtime

| Runtime / flujo | Adaptadores nativos | @jsorm/fetch | Opción recomendada | | --- | --- | --- | --- | | Servidor Node.js | Sí | Sí | Prioriza adaptadores nativos | | Servicio/runtime Bun | Sí | Sí | Prioriza adaptadores nativos si hay acceso directo a DB | | Runtime Deno | Solo SQLite | Sí | Prioriza fetch salvo que uses SQLite explícitamente | | Vercel Edge / Cloudflare Workers / Netlify Edge | No | Sí | Usa @jsorm/runtime + @jsorm/fetch | | CLI, migraciones, jsorm deploy | Sí | No | Usa @jsorm/node + adaptador nativo |

Precaución

@jsorm/fetch es transporte runtime-safe para queries, no un adaptador de migraciones. Reporta supportsMigrations: false, así que los deploys de producción y cambios de esquema deben correr en un entorno Node separado.

Cómo elegir el adaptador correcto

Usa adaptadores nativos cuando

• tu runtime puede abrir conexiones directas a PostgreSQL/MySQL
• ejecutas servicios Node o Bun de larga vida
• quieres el camino por defecto para jsorm deploy
• tu job de deploy o CI es dueño de las migraciones

Usa @jsorm/fetch cuando

• tu runtime es edge-only o fetch-only
• no puedes abrir sockets TCP desde handlers de request
• puedes exponer un gateway HTTP SQL que jsorm consuma
• mantienes migraciones y checks de deploy en un release step Node separado

Ejemplo con adaptador nativo

PostgreSQL

import { createJsorm, defineConnectionSource, defineJsormConfig } from '@jsorm/core';
import { pgAdapter } from '@jsorm/pg';

const main = defineConnectionSource({
  adapter: pgAdapter({
    name: 'main',
    connectionString: process.env.DATABASE_URL!,
    pool: { min: 2, max: 10 },
  }),
});

export default defineJsormConfig({
  connectionSources: { main },
  defaults: { connectionSource: 'main' },
});

export const db = await createJsorm().init();

MySQL

import { createJsorm, defineConnectionSource, defineJsormConfig } from '@jsorm/core';
import { mysqlAdapter } from '@jsorm/mysql';

const main = defineConnectionSource({
  adapter: mysqlAdapter({
    name: 'main',
    uri: process.env.DATABASE_URL!,
    pool: { min: 1, max: 5 },
  }),
});

export default defineJsormConfig({
  connectionSources: { main },
  defaults: { connectionSource: 'main' },
});

export const db = await createJsorm().init();

SQLite

import { createJsorm, defineConnectionSource, defineJsormConfig } from '@jsorm/core';
import { sqliteAdapter } from '@jsorm/sqlite';

const main = defineConnectionSource({
  adapter: sqliteAdapter({
    name: 'main',
    file: process.env.DB_PATH ?? './data/app.db',
  }),
});

export default defineJsormConfig({
  connectionSources: { main },
  defaults: { connectionSource: 'main' },
});

export const db = await createJsorm().init();

Ejemplo con adaptador fetch

Usa imports runtime-safe en bundles edge:

import { createJsorm, defineConnectionSource, defineJsormConfig } from '@jsorm/runtime';
import { fetchAdapter } from '@jsorm/fetch';

const main = defineConnectionSource({
  adapter: fetchAdapter({
    name: 'main',
    dialect: 'postgres',
    endpoint: process.env.SQL_HTTP_ENDPOINT!,
    headers: () => ({
      authorization: `Bearer ${process.env.SQL_HTTP_TOKEN!}`,
    }),
  }),
});

export default defineJsormConfig({
  connectionSources: { main },
  defaults: { connectionSource: 'main' },
});

export const db = await createJsorm().init();

Guía de producción

| Entorno | Runtime de app | Adaptador | Nota de producción | | --- | --- | --- | --- | | API / worker / queue en Node | @jsorm/core o @jsorm/node | Nativo | Mejor opción por defecto para acceso directo y release jobs | | Vercel Edge | @jsorm/runtime | @jsorm/fetch | Mantén jsorm deploy en GitHub Actions u otro paso Node | | Cloudflare Workers | @jsorm/runtime | @jsorm/fetch | Apunta el adaptador a un endpoint HTTP SQL que controles | | Docker / job de deploy en CI | @jsorm/node | Nativo | Ejecuta pnpm exec jsorm deploy --strict --verbose antes del rollout |

Health checks

Usa health checks a nivel de adaptador en código runtime:

const health = await db.healthCheck();
// { main: 'ok', analytics: 'ok' }

Y en flujos Node de deploy o readiness:

pnpm exec jsorm db:check

• Los adaptadores nativos son la opción por defecto para checks previos al deploy.
• Los adaptadores fetch también pueden participar en db.healthCheck(), pero tu endpoint HTTP debe estar accesible, autenticado y sano.

Transacciones

Las transacciones tienen scope de una sola connection source:

await db.transaction(async (tx) => {
  await tx.insert(User, {
    name: 'Alice',
    createdAt: new Date(),
  });
});

• Los adaptadores nativos soportan transacciones de una sola base de datos de forma directa.
• @jsorm/fetch también soporta transacciones, pero tu endpoint HTTP SQL debe implementar begin, commit y rollback.
• No se soportan transacciones cross-database.

Multi-base de datos y clientes con scope

jsorm permite registrar múltiples connectionSources para separar lecturas/escrituras o conectarse a distintas bases de datos. Usa db.use(name) para obtener un cliente ligero con un scope específico, o db.with(name, fn) para aislar operaciones dentro de un bloque.

import { createJsorm, defineConnectionSource, defineJsormConfig } from '@jsorm/core';
import { pgAdapter } from '@jsorm/pg';

const main = defineConnectionSource({ /* ... */ });
const analytics = defineConnectionSource({ /* ... */ });

export default defineJsormConfig({
  connectionSources: { main, analytics },
  defaults: { connectionSource: 'main' },
});

export const db = await createJsorm().init();

// Usa la conexión 'main' por defecto
await db.get(User, { select: { id: true } });

// Cliente con scope para la conexión 'analytics'
const analyticsDb = db.use("analytics");
await analyticsDb.get(User, { select: { id: true } });

// Bloque con scope
await db.with("analytics", async (scoped) => {
  await scoped.raw.execute("SELECT 1");
});

Mejor opción según entorno

1. App Node en producción por defecto: adaptador nativo.
2. Path de requests en edge: @jsorm/runtime + @jsorm/fetch.
3. Migraciones y deploy: @jsorm/node + adaptador nativo.
4. SQLite local embebido: @jsorm/sqlite.

Consejo

Si separas runtime y deploy, mantén el bundle de app mínimo con @jsorm/runtime + @jsorm/fetch, y deja las migraciones en CI Node o en un release job con adaptador nativo.