Serverless / driver edge

Runtimes edge e serverless — Cloudflare Workers, Vercel Edge, Deno — não conseguem abrir sockets TCP brutos, então não podem falar o protocolo de fio do Postgres diretamente. Os endpoints do Kisenon respondem a isso com um gateway SQL HTTP + WebSocket que é compatível no nível de fio com o driver serverless do Neon.

A proposta

Use o pacote npm @neondatabase/serverless exato e sem modificações. Não há pacote de marca Kisenon, nem fork, nem substituições de neonConfig a definir. A única mudança em relação a uma configuração padrão do Neon é o host de conexão — aponte DATABASE_URL para o seu endpoint do Kisenon:

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

Esse é o mesmo host da sua string de conexão Postgres comum — não há um nome de host serverless separado. Pegue-o no cartão do endpoint no console, ou com keon endpoints connection-string <eid>.

Instalação

npm i @neondatabase/serverless

Consultas HTTP com neon()

O cliente de template com tag neon() envia cada consulta como um único POST HTTPS para a rota /sql do endpoint. Ele roda sobre o fetch padrão da web, então é seguro em runtimes edge sem o módulo net do Node. Ideal para consultas avulsas em um Worker ou 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 });
  },
};

Consultas parametrizadas são interpoladas através da tag, de modo que sql`SELECT * FROM users WHERE id = ${id}` é enviada como um parâmetro vinculado, não concatenada como string.

Sessões e transações com Pool / Client

Para sessões com múltiplas instruções, transações interativas ou quando você precisa de uma conexão de longa duração, use Pool (ou Client). Estes fazem tunelamento do protocolo de fio do Postgres por um WebSocket para a rota /v2 do endpoint — o caminho WS é selecionado automaticamente, você não o configura:

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

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

A API completa no estilo pg funciona: pool.connect(), client.query('BEGIN'), prepared statements e assim por diante, tudo sobre o único WebSocket.

Como funciona

Dois transportes terminam no plano de dados regional:

• HTTP — neon() faz um POST para https://<eid>.usc1.kisenon.com/sql com um cabeçalho Neon-Connection-String; o gateway executa a consulta e retorna o envelope de resposta do Neon (command, rowCount, fields, rows).
• WebSocket — Pool/Client fazem upgrade de wss://<eid>.usc1.kisenon.com/v2 e o gateway faz a ponte do protocolo de fio bruto do Postgres (startup, autenticação SCRAM, consulta, dados de linha) através do socket.

Ambos chegam ao mesmo endpoint que a sua string TCP postgres:// alcança, então compartilham os dados, papéis e certificado TLS do seu branch.

Limites e observações

• Sem pool hoje. Cada endpoint é alcançado diretamente; o roteamento de host agrupado -pooler ainda não foi lançado. Use o Pool do próprio driver para reutilização de conexões dentro de um único isolate.
• Despertar do zero. Um endpoint suspenso desperta na sua primeira requisição. Uma consulta HTTP a um endpoint frio pode retornar brevemente um 503 com {"code":"endpoint_waking"} e um cabeçalho Retry-After; o driver repete as requisições HTTP de forma transparente quando aplicável, e um upgrade de WebSocket retido é concluído assim que o endpoint estiver quente. Espere que a primeira requisição após ociosidade demore um pouco mais.
• TLS é obrigatório. O gateway serve um certificado *.usc1.kisenon.com do armazenamento de confiança público — nenhuma CA personalizada é necessária.