서버리스 / 엣지 드라이버

엣지 및 서버리스 런타임(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() 태그드 템플릿 클라이언트는 각 쿼리를 엔드포인트의 /sql 경로로 단일 HTTPS POST로 전송합니다. 웹 표준 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 와이어 프로토콜을 엔드포인트의 /v2 경로로 향하는 WebSocket을 통해 터널링합니다. 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 호스트 라우팅은 아직 출시되지 않았습니다. 단일 아이솔레이트 내에서의 연결 재사용에는 드라이버 자체의 Pool을 사용하세요.
• 제로에서 깨우기. 일시 중지된 엔드포인트는 첫 요청에서 깨어납니다. 콜드 엔드포인트에 대한 HTTP 쿼리는 잠시 503을 {"code":"endpoint_waking"} 및 Retry-After 헤더와 함께 반환할 수 있습니다. 드라이버는 해당하는 경우 HTTP 요청을 투명하게 재시도하며, 보류된 WebSocket 업그레이드는 엔드포인트가 워밍되면 완료됩니다. 유휴 상태 이후 첫 요청은 조금 더 걸릴 것으로 예상하세요.
• TLS는 필수입니다. 게이트웨이는 공개 신뢰 저장소의 *.usc1.kisenon.com 인증서를 제공합니다. 사용자 지정 CA는 필요하지 않습니다.