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

Installieren Sie @kisenon/serverless. Es ist ein Drop-in-Ersatz für den Neon-Serverless-Treiber und das Paket, das die Beispiele auf dieser Seite importieren.

Das Standardpaket @neondatabase/serverless funktioniert ebenfalls unverändert gegen Kisenon — dasselbe Gateway, dasselbe Wire-Format, keine neonConfig-Overrides zu setzen. Nehmen Sie eines von beiden; es gibt genau einen Unterschied, und er steht unten unter HTTP-Abfragen.

So oder so ist die einzige Änderung gegenüber einem Standard-Neon-Setup der Verbindungshost — richten Sie DATABASE_URL auf Ihren Kisenon-Endpoint:

postgres://<user>:<password>@<eid>.<region>.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 connection-string <branch> --project <project-id>.

Installation

npm i @kisenon/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 "@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 });
  },
};

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.

Wenn der SQL-Text ein von Ihnen gebauter String ist statt eines Templates, verwenden Sie sql.query(text, params):

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

Das ist die eine Stelle, an der sich die beiden Pakete unterscheiden. @neondatabase/serverless v1 akzeptiert auch den direkten Aufruf sql(text, params). @kisenon/serverless@0.1.0 tut das nicht — es bindet nur die Tagged-Template-Signatur, ein einfacher String wird also Zeichen für Zeichen gelesen und Postgres lehnt ihn mit 42601 syntax error ab. Nutzen Sie sql.query(), dann verhalten sich beide Pakete identisch.

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 "@kisenon/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>.<region>.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). Es gibt außerdem eine Front-Door-Form https://api.<region>.kisenon.com/sql, bei der der Endpoint aus dem Connection-String im Neon-Connection-String-Header entnommen wird statt aus dem Host-Label — api ist ein reserviertes Front-Door-Label, keine Endpoint-ID.
• WebSocket — Pool/Client upgraden wss://<eid>.<region>.kisenon.com/v2 und das Gateway überbrückt transparent das rohe Postgres-Wire-Protokoll (Startup, Auth, Query, Zeilendaten) über den Socket. Die standardmäßige pipelined-cleartext-Auth des Standard-Treibers wird von einem Shim gehandhabt, sodass seine md5/SCRAM-Berechnungen unverändert funktionieren.

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

Der Edge-Treiber authentifiziert sich sowohl mit md5 als auch mit scram-sha-256 — Compute- Rollen verwenden standardmäßig md5-Passwortverschlüsselung, während neuere Rollen scram verwenden — und das Gateway handhabt beide transparent, sodass Sie nie konfigurieren, welches Ihre Rolle verwendet.

Einschränkungen und Hinweise

• Direkt oder gepoolt. Der Treiber funktioniert sowohl über den direkten Host als auch über den gepoolten <eid>-pooler.<region>.kisenon.com-Host (Transaktionsmodus) — Pooling ist GA und standardmäßig aktiviert. Für die kurzlebigen Verbindungen des Serverless-Treibers ist der gepoolte Host eine natürliche Wahl. Siehe Connection-Strings für gepoolt vs. direkt.
• Aufwecken aus dem Ruhezustand. Ein suspendierter 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 *.<region>.kisenon.com- Zertifikat aus dem öffentlichen Trust-Store — keine eigene CA nötig.
• Rückfall auf den Standardtreiber. @kisenon/serverless@0.1.0 ist gegen den HTTP-Pfad erprobt — neon(), sql.query(), sql.transaction() und die fullResults-Hülle. Falls Sie auf dem WebSocket-Pfad Probleme bekommen, ist @neondatabase/serverless ein unterstützter Tausch und braucht keine weitere Änderung: gleicher Host, gleicher Connection-String, gleiches Gateway.