Serverless / 边缘驱动

边缘和无服务器运行时（Cloudflare Workers、Vercel Edge、Deno）无法打开原始 TCP 套接字，因此不能直接使用 Postgres 线路协议。Kisenon 端点对此以一个在线路层面 与 Neon 无服务器驱动兼容的 HTTP + WebSocket SQL 网关来应答。

要点

使用完全未经修改的 @neondatabase/serverless npm 包。没有 Kisenon 品牌的包，没有分支，也没有需要设置的 neonConfig 覆盖项。相比标准 Neon 配置，唯一的更改是连接主机——将 DATABASE_URL 指向你的 Kisenon 端点：

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

它与你常规的 Postgres 连接字符串是同一个主机——没有单独的无服务器主机名。可从 控制台的端点卡片获取，或使用 keon endpoints connection-string <eid> 获取。

安装

npm i @neondatabase/serverless

使用 neon() 进行 HTTP 查询

neon() 标记模板客户端将每个查询作为单个 HTTPS POST 发送到端点的 /sql 路由。它运行在 Web 标准的 fetch 之上，因此在没有 Node net 模块的边缘运行时中 是安全的。非常适合 Worker 或 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 });
  },
};

参数化查询通过该标记进行插值，因此 sql`SELECT * FROM users WHERE id = ${id}` 会作为绑定参数发送，而不是字符串 拼接。

使用 Pool / Client 进行会话和事务

对于多语句会话、交互式事务，或当你需要长连接时，使用 Pool（或 Client）。它们 将 Postgres 线路协议通过 WebSocket 隧道传输到端点的 /v2 路由——WS 路径会 自动选择，你无需配置：

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

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

完整的 pg 风格 API 都可用：pool.connect()、client.query('BEGIN')、预处理 语句等等，全部在这一个 WebSocket 上运行。

工作原理

两种传输在区域数据平面终结：

• HTTP —— neon() 携带 Neon-Connection-String 头向 https://<eid>.usc1.kisenon.com/sql 发起 POST；网关执行查询并返回 Neon 响应信封（command、rowCount、fields、rows）。
• WebSocket —— Pool/Client 升级 wss://<eid>.usc1.kisenon.com/v2，网关跨套接字桥接原始 Postgres 线路协议 （启动、SCRAM 认证、查询、行数据）。

两者都落在你的 TCP postgres:// 字符串所到达的同一端点上，因此共享你分支的 数据、角色和 TLS 证书。

限制与说明

• 目前不做连接池。 每个端点都是直接访问的；池化的 -pooler 主机路由尚未 发布。请在单个 isolate 内使用驱动自身的 Pool 来复用连接。
• 从零唤醒。 挂起的端点会在第一次请求时唤醒。对冷端点的 HTTP 查询可能会短暂 返回 503，带有 {"code":"endpoint_waking"} 和 Retry-After 头；驱动在适用 时会透明地重试 HTTP 请求，被保持的 WebSocket 升级会在端点变热后完成。空闲后的 第一次请求预计会稍慢一些。
• TLS 是强制的。 网关提供来自公共信任存储的 *.usc1.kisenon.com 证书——无需 自定义 CA。