企业官网建设流程全解析

Neon proxy 的 SQL over HTTP 服务怎么本地启动并发送带参数的查询

【免费下载链接】neonNeon: Serverless Postgres. We separated storage and compute to offer autoscaling, code-like database branching, and scale to zero.项目地址: https://gitcode.com/GitHub_Trending/ne/neon

Neon proxy 除了 TCP/WS 的 Postgres 协议外，还提供一个 SQL over HTTP 服务：接收POST请求中的 SQL 文本，返回 JSON 序列化结果。这个端点不需要驱动，一次 HTTP 请求即可完成查询，也可以直接带参数（$1、$2占位符 +params数组）发送。本文按 proxy/README.md 的说明，在本地搭一个 Postgres、启动 proxy 的 SQL over HTTP 监听，并用curl发送一条带参数的查询，验证返回的 JSON 结果。

适用前提：

• 本地已安装 Docker、Rust 工具链和openssl；
• proxy 的postgresauth backend 用于本地测试（README 原文：useful for local testing），它会从指定数据库里查角色认证信息；
• 本地*.local.neon.build域名解析到127.0.0.1，因为/etc/hosts不支持通配域名，README 用这个域名来模拟按子域名选择项目的行为。

准备本地 Postgres 和认证表

proxy 的postgresauth backend 需要一个 Postgres 实例存放认证元数据。README 给出的最短路径是 Docker：

docker run \ --detach \ --name proxy-postgres \ --env POSTGRES_PASSWORD=proxy-postgres \ --publish 5432:5432 \ postgres:17-bookworm

然后在容器里创建认证 schema、endpoints 表和 proxy 将使用的角色：

docker exec -it proxy-postgres psql -U postgres -c "CREATE SCHEMA IF NOT EXISTS neon_control_plane" docker exec -it proxy-postgres psql -U postgres -c "CREATE TABLE neon_control_plane.endpoints (endpoint_id VARCHAR(255) PRIMARY KEY, allowed_ips VARCHAR(255))" docker exec -it proxy-postgres psql -U postgres -c "CREATE ROLE proxy WITH SUPERUSER LOGIN PASSWORD 'password';"

其中proxy角色就是稍后查询里Neon-Connection-String要连的角色。

可选分支：只有要测试查询取消（query cancellation）时才需要 Redis，本文的查询验证不涉及：

docker run --detach --name proxy-redis --publish 6379:6379 redis:7.0

生成自签名证书

proxy 的 HTTP/WSS 监听走 TLS，本地测试用自签名证书即可：

openssl req -new -x509 -days 365 -nodes -text -out server.crt -keyout server.key -subj "/CN=*.local.neon.build"

证书 CN 必须是*.local.neon.build，这样proxy.local.neon.build、endpoint.local.neon.build等主机名都能匹配。

启动 proxy 并打开 SQL over HTTP 监听

在仓库根目录用testingfeature 编译并运行 proxy：

RUST_LOG=proxy LOGFMT=text cargo run -p proxy --bin proxy --features testing -- \ --auth-backend postgres --auth-endpoint 'postgresql://postgres:proxy-postgres@127.0.0.1:5432/postgres' \ --wss 0.0.0.0:4444 \ -c server.crt -k server.key

参数说明（均按 README 原文）：

• --auth-backend postgres：使用本地 Postgres 做认证，适合本地测试；
• --auth-endpoint：proxy 用来查询角色认证信息的连接串，指向上面启动的proxy-postgres；
• --wss 0.0.0.0:4444：SQL over HTTP 的入口。该参数名为wss，但 proxy/src/binary/proxy.rs 中的注释明确说明：这个 serverless 监听器现在覆盖的不仅是 WebSocket，还包括 SQL over HTTP，即POST /sql请求就发在这个端口上；
• -c / -k：上面的自签名证书和私钥。

如果想跳过编译、直接用已构建的二进制，README 的 SQL over HTTP 一节给出的等价形式是：

LOGFMT=text ./target/debug/proxy -c server.crt -k server.key --auth-backend=postgres --auth-endpoint=postgres://stas@127.0.0.1:5432/stas --wss 0.0.0.0:4444

（示例中stas是 README 作者本机库名，按你自己准备的角色和库替换。）

如果同时启动了 Redis 想测查询取消，README 的命令里还会加--redis-auth-type="plain" --redis-plain="redis://127.0.0.1:6379"。

发送带参数的查询

proxy 和 Postgres 都起来后，向4444端口的/sql路径发POST请求。请求体是 JSON：query为 SQL 文本，params为按$1、$2顺序排列的参数数组；参数值可以是字符串（如 Postgres 数组字面量{{1,2},{"3",4}}），也可以是 JSON 对象：

curl -k -X POST 'https://proxy.local.neon.build:4444/sql' \ -H 'Neon-Connection-String: postgres://proxy:password@proxy.local.neon.build:4444/postgres' \ -H 'Content-Type: application/json' \ --data '{ "query":"SELECT $1::int[] as arr, $2::jsonb as obj, 42 as num", "params":[ "{{1,2},{\"3\",4}}", {"key":"val", "ikey":4242}] }' | jq

说明：

• -k是因为用的是自签名证书，跳过 TLS 校验；
• Neon-Connection-String头指定本次查询要连接的角色和库（这里用的是上面创建的proxy角色）；README 的原始示例使用postgres://stas:pass@...，按你实际创建的角色替换即可；
• 连接串中的主机名用*.local.neon.build，proxy 会按子域名做路由。

README 给出的文档示例响应如下（这是文档中的示例输出，字段结构以此为准）：

{ "command": "SELECT", "fields": [ { "dataTypeID": 1007, "name": "arr" }, { "dataTypeID": 3802, "name": "obj" }, { "dataTypeID": 23, "name": "num" } ], "rowCount": 1, "rows": [ { "arr": [[1,2],[3,4]], "num": 42, "obj": { "ikey": 4242, "key": "val" } } ] }

收到这样一条包含command、fields、rowCount、rows的 JSON，且rows内容与参数绑定一致，说明 SQL over HTTP 链路已经通了。

可选：调整输出格式的两个请求头

请求时可以附加两个可选头来改变返回 JSON 的结构（README “Output options”一节）：

1. Neon-Raw-Text-Output: true：Postgres 值不解析、直接按文本返回。数字、对象、布尔、null 和数组都会以字符串形式给出，适合客户端自己实现解析或复用 node-postgres 的解析库。
2. Neon-Array-Mode: true：行以数组而不是对象返回。这种表示更紧凑，也适用于几个字段同名的场景。

例如给上面的 curl 加一行-H 'Neon-Array-Mode: true'，rows就从对象变成按列顺序排列的数组。

结果判断与限制

• 成功的判断方式：/sql返回上述结构的 JSON。另外可以用 psql 验证 proxy 的 TCP 侧也正常（README 的本地测试命令）：

  PGSSLROOTCERT=./server.crt psql "postgresql://proxy:password@endpoint.local.neon.build:4432/postgres?sslmode=verify-full"

• 请求走的是扩展查询协议：proxy 内部使用扩展查询协议、以文本协议单轮次发送查询，这也是 SQL 注入防护的一部分；同时因为并非所有 Postgres 类型都有二进制表示（如pg_class里的 acl），返回统一走文本协议。

• 类型转换规则（README 列出的主要转换）：

  • int2 / int4 / float4 / float8 → JSON 数字（NaN 和 Inf 仍为文本）；
  • bool、null、text → JSON 布尔、null、字符串；
  • 数组 → JSON 数组；json / jsonb → JSON 对象。 其余类型按字符串传回。

• 响应结构与 node-postgres 对齐：返回 command tag 和列 oid（fields里的dataTypeID），便于和 JS 侧库集成。

• 域名路由：proxy 从子域名推断项目名（如round-rice-566201.somedomain.tld→ 项目round-rice-566201），本地靠*.local.neon.build → 127.0.0.1模拟；如果请求打不到127.0.0.1或端口不对，先检查域名解析和--wss端口是否为4444。

• 认证方式：本文路径使用postgresauth backend（本地测试用途）；console、web等 backend 是生产路由方式，不在本场景范围内。

到这里，本地 SQL over HTTP 的最小闭环就完成了：Docker 起认证库 → 自签名证书 →cargo run带--wss 0.0.0.0:4444启动 →curl POST /sql带参数查询 → 核对 JSON 返回。更多参数和 auth broker 的接法可以继续看 proxy/README.md。

【免费下载链接】neonNeon: Serverless Postgres. We separated storage and compute to offer autoscaling, code-like database branching, and scale to zero.项目地址: https://gitcode.com/GitHub_Trending/ne/neon