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>.<region>.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 card 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>.<region>.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). Há também uma forma de front-door https://api.<region>.kisenon.com/sql, onde o endpoint é obtido da string de conexão no cabeçalho Neon-Connection-String em vez do rótulo do host — api é um rótulo de front-door reservado, não um id de endpoint.
• WebSocket — Pool/Client fazem upgrade de wss://<eid>.<region>.kisenon.com/v2 e o gateway faz a ponte de forma transparente do protocolo de fio bruto do Postgres (startup, auth, consulta, dados de linha) através do socket. A autenticação padrão em texto claro pipelined do driver stock é tratada por um shim, então seus cálculos md5/SCRAM funcionam sem modificações.

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

O driver edge autentica com md5 e scram-sha-256 — roles de compute usam por padrão a criptografia de senha md5 enquanto roles mais novos usam scram — e o gateway trata ambos de forma transparente, então você nunca configura qual deles o seu role usa.

Limites e observações

• Direto ou pooled. O driver funciona tanto sobre o host direto quanto sobre o host pooled <eid>-pooler.<region>.kisenon.com (modo de transação) — o pooling está em GA e ligado por padrão. Para as conexões de vida curta do driver serverless, o host pooled é um ajuste natural. Veja Strings de conexão para pooled-vs-direto.
• 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 *.<region>.kisenon.com do armazenamento de confiança público — nenhuma CA personalizada é necessária.