ClickHouse Managed Postgres で Bun を使用する

Bun は、Postgres クライアント Bun.sql を標準搭載した JavaScript / TypeScript ランタイムです。そのため、ドライバーを別途インストールする必要はありません。このガイドでは、証明書検証付きの TLS で Bun を ClickHouse Managed Postgres に接続し、テーブルの作成、クエリおよびトランザクションの実行を行ったうえで、Bun.serve を使って行データを HTTP で配信します。

前提条件

Bun 1.4 以降。本ガイドは Bun 1.4.2 および Postgres 18 で動作確認済みです。
ClickHouse Cloud のアカウント。
データベース作成用の psql。CREATE DATABASE ステートメントは SQL コンソールで実行することもできます。

ClickHouse Managed Postgres サービスを作成する

ClickHouse Cloud コンソールで New service をクリックし、Postgres を選択します。インスタンスは数分で利用可能になります。詳しい手順については、クイックスタートを参照してください。

接続情報を取得する

サービスを開き、左サイドバーの Connect をクリックします。Directly は選択したままにし、Use SSL をオンにします。これで URL の末尾が sslmode=verify-full&sslrootcert=... になります。Download CA certificate をクリックして、インスタンスの CA 証明書をダウンロードします。このガイドでは、ポート 5432 で直接接続します。Bun.serve アプリは長時間稼働するプロセスであり、Bun.sql は独自の接続プールを持つため、サーバー側のプーラーは必要ありません。短時間で終了する Bun プロセスを多数実行する場合は、PgBouncer 経由で接続するを参照してください。

プロジェクトのセットアップ

プロジェクトを作成します。

mkdir bun-postgres && cd bun-postgres
bun init -y

既存のアプリに追加する場合Bun.sql は Bun に組み込まれており、追加でインストールするものはないため、mkdir と bun init -y は不要です。プロジェクトのルートで接続を構成するに進んでください。また、アプリがサーバーを検証できるように、アプリの起動スクリプトの先頭に NODE_EXTRA_CA_CERTS=./ca-certificate.pem を付けてください。

接続を設定する

ダウンロードした CA 証明書をプロジェクト内に移動し、ファイル名を ca-certificate.pem にリネームします。

mv ~/Downloads/<service-name>-ca-certificate.pem ca-certificate.pem

アプリケーション用のデータベースを作成します。<PASSWORD> とホストは、Connect モーダルに表示される値に置き換えてください。

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/postgres?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE DATABASE guide_bun;"

CREATE DATABASE

guide_bun データベースへの接続 URL を .env に追加します (ファイルが存在しない場合は作成してください) 。Bun は .env を自動的に読み込み、bun からエクスポートされる sql は DATABASE_URL を参照します。

.env

DATABASE_URL=postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_bun?sslmode=verify-full

パスワードに特殊文字が含まれている場合は、URL エンコードしてください。また、.env はバージョン管理の対象外にしてください。次のスクリプトを package.json に追加します。scripts ブロックがすでにある場合は、その中にマージしてください。これらのスクリプトは、NODE_EXTRA_CA_CERTS を介して CA 証明書を Bun に渡します。

package.json

"scripts": {
  "setup": "NODE_EXTRA_CA_CERTS=./ca-certificate.pem bun run setup.ts",
  "queries": "NODE_EXTRA_CA_CERTS=./ca-certificate.pem bun run queries.ts",
  "serve": "NODE_EXTRA_CA_CERTS=./ca-certificate.pem bun run server.ts"
}

Bun がサーバー証明書を検証する仕組み

sslmode=verify-full を指定すると、Bun.sql は証明書チェーンとホスト名の両方を検証します。
コンソールの URL に含まれる sslrootcert パラメータはコピーしないでください。Bun.sql はこのパラメータを解釈せず、ランタイム設定としてそのままサーバーへ渡します。その結果、unrecognized configuration parameter "sslrootcert" というエラーで接続に失敗します。
NODE_EXTRA_CA_CERTS は、Bun の起動時点で環境変数として設定されている必要があります。Bun はこの値を .env から読み込まないため、スクリプト内で設定しています。
Bun 1.4.2 では、ダウンロードした証明書を SQL の tls: { ca } オプションで渡すと、certificate signature failure というエラーで失敗します。代わりに NODE_EXTRA_CA_CERTS を使用してください。

テーブルを作成する

setup.ts を作成します。このスクリプトは session の TLS の状態を出力してから、todos テーブルを作成します。

setup.ts

import { sql } from "bun";

const [tls] = await sql`SELECT ssl, version FROM pg_stat_ssl WHERE pid = pg_backend_pid()`;
console.log("TLS:", tls);

await sql`
  CREATE TABLE IF NOT EXISTS todos (
    id         integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    title      text NOT NULL,
    done       boolean NOT NULL DEFAULT false,
    created_at timestamptz NOT NULL DEFAULT now()
  )
`;
console.log("Table todos is ready");

await sql.close();

次のコマンドを実行します：

bun run setup

$ NODE_EXTRA_CA_CERTS=./ca-certificate.pem bun run setup.ts
TLS: {
  ssl: true,
  version: "TLSv1.3",
}
Table todos is ready

証明書が検証されていることを確認するため、CA証明書を指定せずにこのファイルを実行します。接続が拒否されることがわかります。

bun run setup.ts

error: unable to verify the first certificate
 errno: 0,
  code: "UNABLE_TO_VERIFY_LEAF_SIGNATURE"

データベースにクエリを実行する

Bun.sql ではタグ付きテンプレートを使用します。埋め込まれた値はすべてバインドパラメータとして送信されるため、ユーザー入力をそのまま渡しても安全です。queries.ts を作成します。

queries.ts

import { sql } from "bun";

// Interpolated values are sent as bind parameters, never spliced into the SQL text
const title = "Download the CA certificate";
const [first] = await sql`INSERT INTO todos (title, done) VALUES (${title}, true) RETURNING *`;
console.log("Inserted:", first);

// Insert several rows at once with the sql(array) helper
const rows = [{ title: "Connect with Bun.sql" }, { title: "Serve rows with Bun.serve" }];
await sql`INSERT INTO todos ${sql(rows)}`;

// Both statements commit together, or neither does
await sql.begin(async (tx) => {
  const [todo] = await tx`INSERT INTO todos (title) VALUES ('Write a transaction') RETURNING id`;
  await tx`UPDATE todos SET done = true WHERE id = ${todo.id}`;
});

const open = await sql`SELECT id, title FROM todos WHERE done = ${false} ORDER BY id`;
console.log("Open todos:", open);

await sql.close();

sql.begin はコールバックをトランザクション内で実行します。コールバックが正常に戻るとコミットし、例外がスローされるとロールバックします。実行してみましょう：

bun run queries

$ NODE_EXTRA_CA_CERTS=./ca-certificate.pem bun run queries.ts
Inserted: {
  id: 1,
  title: "Download the CA certificate",
  done: true,
  created_at: 2026-09-30T16:51:23.040Z,
}
Open todos: [
  {
    id: 2,
    title: "Connect with Bun.sql",
  }, {
    id: 3,
    title: "Serve rows with Bun.serve",
  }, count: 2, command: "SELECT", lastInsertRowid: null,
  affectedRows: null
]

HTTP 経由で行を返す

行の一覧取得と作成を行う /todos エンドポイントを持つ server.ts を作成します。

server.ts

import { sql } from "bun";

const server = Bun.serve({
  port: 3106,
  routes: {
    "/todos": {
      GET: async () => {
        const todos = await sql`SELECT id, title, done, created_at FROM todos ORDER BY id`;
        return Response.json(todos);
      },
      POST: async (req) => {
        const { title } = await req.json();
        const [todo] = await sql`INSERT INTO todos (title) VALUES (${title}) RETURNING *`;
        return Response.json(todo, { status: 201 });
      },
    },
  },
});

console.log(`Listening on ${server.url}`);

サーバーを起動します。

bun run serve

$ NODE_EXTRA_CA_CERTS=./ca-certificate.pem bun run server.ts
Listening on http://localhost:3106/

別の端末で、行を 1 つ追加します：

curl -X POST http://localhost:3106/todos -H 'Content-Type: application/json' -d '{"title": "Take a screenshot"}'

{"id":5,"title":"Take a screenshot","done":false,"created_at":"2026-09-30T16:51:30.372Z"}

動作確認

ブラウザで http://localhost:3106/todos を開くと、すべての行を確認できます。レスポンスは次のようになります (読みやすいように整形しています) 。

[
  {"id":1,"title":"Download the CA certificate","done":true,"created_at":"2026-09-30T16:51:23.040Z"},
  {"id":2,"title":"Connect with Bun.sql","done":false,"created_at":"2026-09-30T16:51:23.136Z"},
  {"id":3,"title":"Serve rows with Bun.serve","done":false,"created_at":"2026-09-30T16:51:23.136Z"},
  {"id":4,"title":"Write a transaction","done":true,"created_at":"2026-09-30T16:51:23.184Z"},
  {"id":5,"title":"Take a screenshot","done":false,"created_at":"2026-09-30T16:51:30.372Z"}
]

コンソールで SQL コンソール を開き、guide_bun、public、todos の順に展開すると、同じ行が表示されます：

id	title	done	created_at
1	Download the CA certificate	true	2026-09-30 16:51:23.04083+00
2	Connect with Bun.sql	false	2026-09-30 16:51:23.136975+00
3	Serve rows with Bun.serve	false	2026-09-30 16:51:23.136975+00
4	Write a transaction	true	2026-09-30 16:51:23.184716+00
5	Take a screenshot	false	2026-09-30 16:51:30.372292+00

PgBouncer 経由で接続する

短時間で終了する Bun プロセスを多数実行する場合は、代わりに同梱の PgBouncer を経由して接続してください。Connect モーダルで via PgBouncer を選択し、DATABASE_URL のポートを 6432 に変更します。CA 証明書と sslmode=verify-full は変更不要です。 PgBouncer はトランザクションプーリングモードで動作します。Bun.sql はデフォルトで名前付きプリペアドステートメントを使用しますが、当社のテストでは PgBouncer 経由でも問題なく動作しました。prepared statement does not exist エラーが発生する場合は、prepare: false を指定してクライアントを作成してください。

import { SQL } from "bun";

const sql = new SQL(process.env.DATABASE_URL!, { prepare: false });

prepare は URL に含めず、オプションとして渡してください。sslrootcert と同様に、prepare=false を URL パラメータとして指定すると、サーバーに転送されて拒否されます。

次のステップ

接続: 接続文字列、PgBouncer、TLS
設定: Postgres および PgBouncer のパラメータの変更
読み取りレプリカ: 読み取り処理のスケーリング
Bun SQL ドキュメント: Bun.sql API の完全なリファレンス

はじめる

機能

ガイド

料金

ClickHouse 連携

移行

監視

よくある質問

ClickHouse Managed Postgres で Bun を使用する

前提条件

ClickHouse Managed Postgres サービスを作成する

接続情報を取得する

プロジェクトのセットアップ

接続を設定する

テーブルを作成する

データベースにクエリを実行する

HTTP 経由で行を返す

動作確認

PgBouncer 経由で接続する

次のステップ

​前提条件

​ClickHouse Managed Postgres サービスを作成する

​接続情報を取得する

​プロジェクトのセットアップ

​接続を設定する

​テーブルを作成する

​データベースにクエリを実行する

​HTTP 経由で行を返す

​動作確認

​PgBouncer 経由で接続する

​次のステップ

前提条件

ClickHouse Managed Postgres サービスを作成する

接続情報を取得する

プロジェクトのセットアップ

接続を設定する

テーブルを作成する

データベースにクエリを実行する

HTTP 経由で行を返す

動作確認

PgBouncer 経由で接続する

次のステップ