서버리스 / 엣지 드라이버

엣지 및 서버리스 런타임(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>.<region>.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>.<region>.kisenon.com/sql로 POST합니다; 게이트웨이는 쿼리를 실행하고 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 와이어 프로토콜(시작, 인증, 쿼리, 행 데이터)을 소켓 너머로 투명하게 브리지합니다. 표준 드라이버의 기본 파이프라인 평문 인증은 심이 처리하므로, 드라이버의 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는 필요하지 않습니다.