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.