Serverless / pilote edge

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

L'argument clé

Utilisez le paquet npm @neondatabase/serverless exact et non modifié. Il n'y a aucun paquet de marque Kisenon, aucun fork et aucune surcharge neonConfig à définir. 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>.usc1.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 d'endpoint dans la console, ou avec keon endpoints connection-string <eid>.

Installation

npm i @neondatabase/serverless

Requêtes HTTP avec neon()

Le client à modèle balisé neon() envoie chaque requête sous forme d'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 Node net. Idéal pour des requêtes ponctuelles dans un Worker ou une 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 });
  },
};

Les requêtes paramétrées sont interpolées via la balise, si bien que sql`SELECT * FROM users WHERE id = ${id}` est envoyée comme un paramètre lié, et non concaténée dans une chaîne.

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, utilisez Pool (ou Client). Ceux-ci tunnelisent le protocole filaire Postgres sur un WebSocket vers la route /v2 de l'endpoint — le chemin WS est sélectionné automatiquement, vous ne le configurez pas :

import { Pool } from "@neondatabase/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 requêtes préparées, etc., le tout sur l'unique WebSocket.

Comment ça marche

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

• HTTP — neon() effectue un POST vers https://<eid>.usc1.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).
• WebSocket — Pool/Client mettent à niveau wss://<eid>.usc1.kisenon.com/v2 et la passerelle fait le pont du protocole filaire Postgres brut (démarrage, authentification SCRAM, requête, données de ligne) à travers le socket.

Les deux aboutissent au même endpoint que celui atteint par votre chaîne TCP postgres://, ils partagent donc les données, les rôles et le certificat TLS de votre branche.

Limites et remarques

• Non mutualisé aujourd'hui. Chaque endpoint est atteint directement ; le routage d'hôte mutualisé -pooler n'est pas encore livré. Utilisez le Pool propre à votre pilote pour la réutilisation de connexions au sein d'un même isolat.
• 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 un 503 avec {"code":"endpoint_waking"} et un en-tête Retry-After ; le pilote réessaie les requêtes HTTP de façon transparente lorsque c'est applicable, et une mise à niveau WebSocket maintenue se termine une fois l'endpoint chaud. Attendez-vous à ce que la première requête après une période d'inactivité prenne un peu plus de temps.
• TLS est obligatoire. La passerelle sert un certificat *.usc1.kisenon.com issu du magasin de confiance public — aucune CA personnalisée n'est nécessaire.