Serverless / 边缘驱动

边缘和无服务器运行时 —— Cloudflare Workers、Vercel Edge、Deno —— 无法打开原始 TCP 套接字，因此它们无法直接使用 Postgres 线路 协议。Kisenon 端点通过一个与 Neon serverless 驱动线路兼容 的 HTTP + WebSocket SQL 网关来应对这一点。

卖点

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

postgres://<user>:<password>@<eid>.<region>.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() 向 https://<eid>.<region>.kisenon.com/sql 发起 POST， 并带一个 Neon-Connection-String 头；网关运行查询并返回 Neon 响应信封（command、rowCount、fields、rows）。还 有一个前门形式 https://api.<region>.kisenon.com/sql，其中 端点取自 Neon-Connection-String 头中的连接字符串， 而非主机标签 —— api 是一个保留的前门标签， 而非端点 id。
• WebSocket —— Pool/Client 升级 wss://<eid>.<region>.kisenon.com/v2， 网关透明地在套接字上桥接原始 Postgres 线路协议（启动、 认证、查询、行数据）。标准驱动默认的 流水线明文认证由一个 shim 处理，因此其 md5/SCRAM 计算无需修改即可工作。

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

边缘驱动使用 md5 和 scram-sha-256 两者进行身份验证 —— 计算 角色默认使用 md5 密码加密，而较新的角色使用 scram —— 且 网关透明地处理两者，因此你永远不必配置你的角色使用哪一个。

限制与说明

• 直连或池化。 该驱动在直连主机和 池化的 <eid>-pooler.<region>.kisenon.com 主机（事务模式）上都可工作 —— 池化 已 GA 并默认开启。对于无服务器驱动的短生命周期连接， 池化主机是天然的契合。参见 连接字符串 了解池化与直连。
• 从零唤醒。 一个挂起的端点会在其第一个请求时唤醒。一个 对冷端点的 HTTP 查询可能会短暂返回 503 并带 {"code":"endpoint_waking"} 以及一个 Retry-After 头；驱动 在适用之处透明地重试 HTTP 请求，而一个被保持的 WebSocket 升级会在端点温热后完成。预计空闲之后的第一个 请求会多花一点时间。
• TLS 是强制的。 网关从公共信任库提供一个 *.<region>.kisenon.com 证书 —— 无需自定义 CA。