サーバーレス / エッジドライバー

エッジおよびサーバーレスランタイム（Cloudflare Workers、Vercel Edge、Deno） は生の TCP ソケットを開けないため、Postgres ワイヤープロトコルを直接 話すことができません。Kisenon エンドポイントはこれに対し、Neon サーバーレス ドライバーとワイヤー互換の HTTP + WebSocket SQL ゲートウェイで応えます。

要点

@kisenon/serverless を インストールしてください。Neon serverless ドライバのドロップイン置き換えであり、 このページの例が import しているパッケージです。

標準の @neondatabase/serverless パッケージも、未改変のまま Kisenon に対して動作します — 同じゲートウェイ、同じ ワイヤ形式で、設定する neonConfig のオーバーライドもありません。どちらを選んでも 構いません。両者の違いは 1 点だけで、下の HTTP クエリの節で説明します。

いずれの場合も、標準的な Neon のセットアップからの唯一の変更は接続ホストです。 DATABASE_URL を Kisenon エンドポイントに向けてください:

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

これは通常の Postgres 接続文字列と同じホストです。別のサーバーレス用 ホスト名はありません。コンソールのエンドポイントカードから、または keon connection-string <branch> --project <project-id> で取得します。

インストール

npm i @kisenon/serverless

neon() による HTTP クエリ

neon() タグ付きテンプレートクライアントは、各クエリをエンドポイントの /sql ルートへの単一の HTTPS POST として送信します。Web 標準の fetch 上で 動作するため、Node の net モジュールがないエッジランタイムでも安全です。 Worker や Edge Function での一発のクエリに最適です:

import { neon } from "@kisenon/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}` は文字列連結ではなく バインドされたパラメーターとして送信されます。

SQL テキストをテンプレートではなく文字列として組み立てた場合は、 sql.query(text, params) を使用します。

const rows = await sql.query("SELECT * FROM users WHERE id = $1", [id]);

両パッケージが唯一異なるのがここです。 @neondatabase/serverless v1 は直接 呼び出し sql(text, params) も受け付けます。@kisenon/serverless@0.1.0 は 受け付けません — タグ付きテンプレートのシグネチャのみをバインドするため、 素の文字列は 1 文字ずつ読み取られ、Postgres は 42601 syntax error で拒否します。 sql.query() を使えば、両パッケージは同じように動作します。

Pool / Client によるセッションとトランザクション

複数ステートメントのセッション、対話型トランザクション、または長寿命の 接続が必要な場合は、Pool（または Client）を使用します。これらは Postgres ワイヤープロトコルをエンドポイントの /v2 ルートへの WebSocket 経由で トンネルします — WS パスは自動的に選択され、設定は不要です:

import { Pool } from "@kisenon/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 上で動作します。

仕組み

2 つのトランスポートがリージョナルデータプレーンで終端します:

• 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 は不要です。
• 標準ドライバへのフォールバック。 @kisenon/serverless@0.1.0 は HTTP パス — neon()、sql.query()、sql.transaction()、fullResults エンベロープ — で 検証されています。WebSocket パスで問題が出た場合、@neondatabase/serverless へ 差し替えても他に変更は不要です。ホストも接続文字列もゲートウェイも同じです。