Serverless / controlador edge

Los runtimes edge y serverless — Cloudflare Workers, Vercel Edge, Deno — no pueden abrir sockets TCP en bruto, así que no pueden hablar el protocolo de cable de Postgres directamente. Los endpoints de Kisenon responden a esto con una pasarela SQL de HTTP + WebSocket que es compatible a nivel de cable con el controlador serverless de Neon.

La propuesta

Usa el paquete npm @neondatabase/serverless exacto y sin modificar. No hay ningún paquete de marca Kisenon, ni fork, ni sustituciones de neonConfig que configurar. El único cambio respecto a una configuración estándar de Neon es el host de conexión — apunta DATABASE_URL a tu endpoint de Kisenon:

postgres://<user>:<password>@<eid>.usc1.kisenon.com/<db>

Ese es el mismo host que tu cadena de conexión Postgres habitual — no hay un nombre de host serverless aparte. Obtenlo de la tarjeta del endpoint en la consola, o con keon endpoints connection-string <eid>.

Instalación

npm i @neondatabase/serverless

Consultas HTTP con neon()

El cliente de plantilla etiquetada neon() envía cada consulta como un único POST HTTPS a la ruta /sql del endpoint. Se ejecuta sobre el fetch estándar de la web, por lo que es seguro en runtimes edge sin el módulo net de Node. Ideal para consultas puntuales en un Worker o una Edge Function:

import { neon } from "@neondatabase/serverless";

export default {
  async fetch(request, env) {
    const sql = neon(env.DATABASE_URL);
    const [row] = await sql`SELECT 1 AS n`;
    return Response.json({ n: row.n });
  },
};

Las consultas parametrizadas se interpolan a través de la etiqueta, de modo que sql`SELECT * FROM users WHERE id = ${id}` se envía como un parámetro vinculado, no concatenado como cadena.

Sesiones y transacciones con Pool / Client

Para sesiones de varias instrucciones, transacciones interactivas o cuando necesitas una conexión de larga duración, usa Pool (o Client). Estos tunelizan el protocolo de cable de Postgres sobre un WebSocket hacia la ruta /v2 del endpoint — la ruta WS se selecciona automáticamente, no la configuras:

import { Pool } from "@neondatabase/serverless";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const { rows } = await pool.query("SELECT 1");

La API completa de estilo pg funciona: pool.connect(), client.query('BEGIN'), sentencias preparadas, etc., todo sobre el único WebSocket.

Cómo funciona

Dos transportes terminan en el plano de datos regional:

• HTTP — neon() hace un POST a https://<eid>.usc1.kisenon.com/sql con una cabecera Neon-Connection-String; la pasarela ejecuta la consulta y devuelve el sobre de respuesta de Neon (command, rowCount, fields, rows).
• WebSocket — Pool/Client actualizan wss://<eid>.usc1.kisenon.com/v2 y la pasarela puentea el protocolo de cable de Postgres en bruto (arranque, autenticación SCRAM, consulta, datos de fila) a través del socket.

Ambos llegan al mismo endpoint que alcanza tu cadena TCP postgres://, así que comparten los datos, roles y certificado TLS de tu rama.

Límites y notas

• Sin pool hoy. Cada endpoint se alcanza directamente; el enrutamiento de host agrupado -pooler aún no está disponible. Usa el Pool propio de tu controlador para reutilizar conexiones dentro de un mismo aislado.
• Despertar desde cero. Un endpoint suspendido despierta en su primera solicitud. Una consulta HTTP a un endpoint frío puede devolver brevemente un 503 con {"code":"endpoint_waking"} y una cabecera Retry-After; el controlador reintenta las solicitudes HTTP de forma transparente cuando procede, y una actualización WebSocket retenida se completa una vez que el endpoint está caliente. Espera que la primera solicitud tras un periodo de inactividad tarde un poco más.
• TLS es obligatorio. La pasarela sirve un certificado *.usc1.kisenon.com desde el almacén de confianza público — no se necesita una CA personalizada.