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

Instale @kisenon/serverless. É uma substituição direta do driver serverless da Neon, e é o pacote que os exemplos desta página importam.

O pacote padrão @neondatabase/serverless também funciona contra o Kisenon, sem modificações — o mesmo gateway, o mesmo formato de fio, nenhuma substituição de neonConfig a definir. Escolha qualquer um; há uma única diferença entre eles, apontada abaixo em Consultas HTTP.

De um jeito ou de outro, 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 connection-string <branch> --project <project-id>.

Instalação

npm i @kisenon/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 "@kisenon/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.

Quando o texto SQL é uma string que você montou em vez de um template, use sql.query(text, params):

const rows = await sql.query("SELECT * FROM users WHERE id = $1", [id]);

Este é o único ponto em que os dois pacotes diferem. @neondatabase/serverless v1 também aceita a chamada direta sql(text, params). O @kisenon/serverless@0.1.0 não aceita — ele vincula apenas a assinatura de template com tag, então uma string simples é lida caractere a caractere e o Postgres a rejeita com 42601 syntax error. Use sql.query() e os dois pacotes se comportam igual.

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 "@kisenon/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.
• Voltando ao driver padrão. O @kisenon/serverless@0.1.0 é exercitado no caminho HTTP — neon(), sql.query(), sql.transaction() e o envelope fullResults. Se você tiver problemas no caminho WebSocket, @neondatabase/serverless é uma troca suportada e não exige nenhuma outra mudança: mesmo host, mesma string de conexão, mesmo gateway.