Serverless / pilote edge

Les runtimes edge et serverless — Cloudflare Workers, Vercel Edge, Deno — ne peuvent pas ouvrir de sockets TCP bruts, ils ne peuvent donc pas parler le protocole filaire Postgres directement. Les endpoints Kisenon répondent à cela avec une passerelle SQL HTTP + WebSocket qui est compatible au niveau filaire avec le pilote serverless Neon.

L'argument

Installez @kisenon/serverless. C'est un remplacement direct du pilote serverless Neon, et c'est le paquet qu'importent les exemples de cette page.

Le paquet standard @neondatabase/serverless fonctionne lui aussi contre Kisenon, sans modification — même passerelle, même format de fil, aucun remplacement neonConfig à définir. Prenez l'un ou l'autre ; il y a une seule différence entre eux, signalée ci-dessous sous Requêtes HTTP.

Dans les deux cas, le seul changement par rapport à une configuration Neon standard est l'hôte de connexion — pointez DATABASE_URL vers votre endpoint Kisenon :

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

C'est le même hôte que votre chaîne de connexion Postgres habituelle — il n'y a pas de nom d'hôte serverless distinct. Récupérez-le depuis la carte de l'endpoint dans la console, ou avec keon connection-string <branch> --project <project-id>.

Installation

npm i @kisenon/serverless

Requêtes HTTP avec neon()

Le client de template balisé neon() envoie chaque requête comme un unique POST HTTPS vers la route /sql de l'endpoint. Il s'exécute sur le fetch standard du Web, il est donc sûr dans les runtimes edge sans module net Node. Idéal pour des requêtes ponctuelles dans un Worker ou une 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 });
  },
};

Les requêtes paramétrées s'interpolent à travers la balise, de sorte que sql`SELECT * FROM users WHERE id = ${id}` est envoyé comme un paramètre lié, pas concaténé en chaîne.

Quand le texte SQL est une chaîne que vous avez construite plutôt qu'un template, utilisez sql.query(text, params) :

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

C'est le seul point où les deux paquets diffèrent. @neondatabase/serverless v1 accepte aussi l'appel direct sql(text, params). @kisenon/serverless@0.1.0 ne l'accepte pas — il ne lie que la signature de template balisé, donc une chaîne simple est lue caractère par caractère et Postgres la rejette avec 42601 syntax error. Utilisez sql.query() et les deux paquets se comportent à l'identique.

Sessions et transactions avec Pool / Client

Pour des sessions multi-instructions, des transactions interactives, ou lorsque vous avez besoin d'une connexion à longue durée de vie, utilisez Pool (ou Client). Ceux-ci tunnellisent le protocole filaire Postgres via un WebSocket vers la route /v2 de l'endpoint — le chemin WS est sélectionné automatiquement, vous ne le configurez pas :

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

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

L'API complète de style pg fonctionne : pool.connect(), client.query('BEGIN'), les instructions préparées, et ainsi de suite, le tout sur le même WebSocket.

Comment ça fonctionne

Deux transports se terminent au niveau du plan de données régional :

• HTTP — neon() envoie un POST à https://<eid>.<region>.kisenon.com/sql avec un en-tête Neon-Connection-String ; la passerelle exécute la requête et renvoie l'enveloppe de réponse Neon (command, rowCount, fields, rows). Il existe aussi une forme de porte d'entrée https://api.<region>.kisenon.com/sql, où l'endpoint est tiré de la chaîne de connexion dans l'en-tête Neon-Connection-String plutôt que du libellé d'hôte — api est un libellé de porte d'entrée réservé, pas un id d'endpoint.
• WebSocket — Pool/Client mettent à niveau wss://<eid>.<region>.kisenon.com/v2 et la passerelle relaie de façon transparente le protocole filaire Postgres brut (startup, auth, query, données de ligne) à travers le socket. L'auth pipelinée en clair par défaut du pilote standard est gérée par un shim, de sorte que ses calculs md5/SCRAM fonctionnent sans modification.

Les deux atterrissent sur le même endpoint que votre chaîne TCP postgres:// atteint, de sorte qu' ils partagent les données, rôles et certificat TLS de votre branche.

Le pilote edge s'authentifie avec md5 et scram-sha-256 — les rôles compute utilisent par défaut le chiffrement de mot de passe md5 tandis que les rôles plus récents utilisent scram — et la passerelle gère les deux de façon transparente, de sorte que vous ne configurez jamais lequel votre rôle utilise.

Limites et notes

• Direct ou regroupé. Le pilote fonctionne à la fois sur l'hôte direct et sur l'hôte regroupé <eid>-pooler.<region>.kisenon.com (mode transaction) — le regroupement est GA et activé par défaut. Pour les connexions de courte durée du pilote serverless, l'hôte regroupé est un choix naturel. Voir Chaînes de connexion pour regroupé-vs-direct.
• Réveil depuis zéro. Un endpoint suspendu se réveille à sa première requête. Une requête HTTP vers un endpoint froid peut brièvement renvoyer 503 avec {"code":"endpoint_waking"} et un en-tête Retry-After ; le pilote réessaie les requêtes HTTP de façon transparente là où c'est applicable, et une mise à niveau WebSocket en attente s'achève une fois l'endpoint chaud. Attendez-vous à ce que la première requête après inactivité prenne un instant de plus.
• TLS est obligatoire. La passerelle sert un certificat *.<region>.kisenon.com du magasin de confiance public — aucune CA personnalisée nécessaire.
• Repli sur le pilote standard. @kisenon/serverless@0.1.0 est éprouvé sur le chemin HTTP — neon(), sql.query(), sql.transaction() et l'enveloppe fullResults. Si vous rencontrez un problème sur le chemin WebSocket, @neondatabase/serverless est un échange pris en charge et ne demande aucun autre changement : même hôte, même chaîne de connexion, même passerelle.