Serverless / controlador edge

Los runtimes edge y serverless — Cloudflare Workers, Vercel Edge, Deno — no pueden abrir sockets TCP en bruto, por lo 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 paquete con marca Kisenon, ni fork, ni overrides de neonConfig que establecer. 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>.<region>.kisenon.com/<db>

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

Instalar

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, así 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 múltiples sentencias, 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 a 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 al 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 POST a https://<eid>.<region>.kisenon.com/sql con un encabezado Neon-Connection-String; la pasarela ejecuta la consulta y devuelve el sobre de respuesta de Neon (command, rowCount, fields, rows). También existe una forma de puerta de entrada https://api.<region>.kisenon.com/sql, donde el endpoint se toma de la cadena de conexión en el encabezado Neon-Connection-String en lugar de la etiqueta de host — api es una etiqueta de puerta de entrada reservada, no un id de endpoint.
• WebSocket — Pool/Client actualizan wss://<eid>.<region>.kisenon.com/v2 y la pasarela puentea de forma transparente el protocolo de cable en bruto de Postgres (arranque, autenticación, consulta, datos de fila) a través del socket. La autenticación cleartext canalizada predeterminada del controlador estándar es gestionada por un shim, de modo que sus cálculos md5/SCRAM funcionan sin modificar.

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

El controlador edge se autentica con ambos md5 y scram-sha-256 — los roles de cómputo usan por defecto cifrado de contraseña md5 mientras que los roles más nuevos usan scram — y la pasarela gestiona ambos de forma transparente, así que nunca configuras cuál usa tu rol.

Límites y notas

• Directo o agrupado. El controlador funciona sobre el host directo y el host agrupado <eid>-pooler.<region>.kisenon.com (modo de transacción) — el pooling está GA y activado por defecto. Para las conexiones de corta duración del controlador serverless el host agrupado es un ajuste natural. Consulta Cadenas de conexión para agrupado-vs-directo.
• Activación desde cero. Un endpoint suspendido se activa en su primera solicitud. Una consulta HTTP a un endpoint frío puede devolver brevemente 503 con {"code":"endpoint_waking"} y un encabezado Retry-After; el controlador reintenta las solicitudes HTTP de forma transparente donde corresponde, y una actualización de WebSocket retenida se completa una vez que el endpoint está caliente. Espera que la primera solicitud tras la inactividad tarde un momento más.
• TLS es obligatorio. La pasarela sirve un certificado *.<region>.kisenon.com del almacén de confianza público — no se necesita una CA personalizada.