Serverless / Edge-Treiber

Edge- und Serverless-Runtimes — Cloudflare Workers, Vercel Edge, Deno — können keine rohen TCP-Sockets öffnen und somit das Postgres-Wire-Protokoll nicht direkt sprechen. Kisenon-Endpoints beantworten dies mit einem HTTP- + WebSocket-SQL-Gateway, das wire-kompatibel mit dem Neon-Serverless-Treiber ist.

Die Kernidee

Verwenden Sie das exakte, unveränderte @neondatabase/serverless-npm-Paket. Es gibt kein Kisenon-Paket, keinen Fork und keine neonConfig-Overrides zu setzen. Die einzige Änderung gegenüber einem Standard-Neon-Setup ist der Verbindungshost — richten Sie DATABASE_URL auf Ihren Kisenon-Endpoint:

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

Das ist derselbe Host wie in Ihrem regulären Postgres-Connection-String — es gibt keinen separaten Serverless-Hostnamen. Holen Sie ihn aus der Endpoint-Karte in der Konsole oder mit keon endpoints connection-string <eid>.

Installation

npm i @neondatabase/serverless

HTTP-Abfragen mit neon()

Der neon()-Tagged-Template-Client sendet jede Abfrage als einzelnes HTTPS-POST an die /sql-Route des Endpoints. Er läuft auf dem Web-Standard-fetch und ist daher in Edge-Runtimes ohne Node-net-Modul sicher. Ideal für einmalige Abfragen in einem Worker oder einer 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 });
  },
};

Parametrisierte Abfragen werden durch das Tag interpoliert, sodass sql`SELECT * FROM users WHERE id = ${id}` als gebundener Parameter gesendet wird und nicht per String-Verkettung.

Sitzungen und Transaktionen mit Pool / Client

Für Multi-Statement-Sitzungen, interaktive Transaktionen oder wenn Sie eine langlebige Verbindung benötigen, nutzen Sie Pool (oder Client). Diese tunneln das Postgres-Wire-Protokoll über einen WebSocket an die /v2-Route des Endpoints — der WS-Pfad wird automatisch gewählt, Sie konfigurieren ihn nicht:

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

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

Die vollständige pg-artige API funktioniert: pool.connect(), client.query('BEGIN'), Prepared Statements und so weiter, alles über den einen WebSocket.

Wie es funktioniert

Zwei Transporte terminieren an der regionalen Data-Plane:

• HTTP — neon() sendet ein POST an https://<eid>.usc1.kisenon.com/sql mit einem Neon-Connection-String-Header; das Gateway führt die Abfrage aus und gibt das Neon-Response-Envelope zurück (command, rowCount, fields, rows).
• WebSocket — Pool/Client upgraden wss://<eid>.usc1.kisenon.com/v2 und das Gateway überbrückt das rohe Postgres-Wire-Protokoll (Startup, SCRAM-Auth, Query, Zeilendaten) über den Socket.

Beide landen auf demselben Endpoint, den Ihr TCP-postgres://-String erreicht, und teilen sich daher die Daten, Rollen und das TLS-Zertifikat Ihres Branches.

Einschränkungen und Hinweise

• Heute ungepoolt. Jeder Endpoint wird direkt erreicht; das gepoolte -pooler-Host-Routing ist noch nicht ausgeliefert. Nutzen Sie den eigenen Pool Ihres Treibers für Verbindungswiederverwendung innerhalb eines einzelnen Isolate.
• Aufwecken aus dem Ruhezustand. Ein pausierter Endpoint wacht bei seiner ersten Anfrage auf. Eine HTTP-Abfrage an einen kalten Endpoint kann kurz 503 mit {"code":"endpoint_waking"} und einem Retry-After-Header zurückgeben; der Treiber wiederholt HTTP-Anfragen transparent, wo zutreffend, und ein gehaltenes WebSocket-Upgrade wird abgeschlossen, sobald der Endpoint warm ist. Erwarten Sie, dass die erste Anfrage nach Leerlauf etwas länger dauert.
• TLS ist obligatorisch. Das Gateway liefert ein *.usc1.kisenon.com-Zertifikat aus dem öffentlichen Trust-Store — keine eigene CA nötig.