Neon

Hyperdrive で Neon に接続するには、次の手順に従います。

新しいユーザーを作成し、データベースの接続文字列を取得すれば、既存の任意の Neon データベースに Hyperdrive を接続できます。

1. Neon dashboard ↗ を開き、接続したいプロジェクト（データベース）を選択します。
2. サイドバーから Roles を選び、New Role を選択します。名前に hyperdrive-user（または任意の名前）を入力し、パスワードをコピーします。パスワードは再表示されないため、保存しておかないとリセットが必要になります。
3. サイドバーから Dashboard を選び、Connection Details ペインを開きます。Hyperdrive が接続に使う branch、database、role（例: hyperdrive-user）が選択されていることを確認します。
4. psql を選択し、connection pooling のチェックを外します。テキストボックスの接続文字列（postgres://hyperdrive-user@... で始まるもの）を控えます。

接続文字列とパスワードが揃えば、Hyperdrive のデータベース設定を作成できます。

Hyperdrive を設定するには、次の情報が必要です。

• データベースの IP アドレス（またはホスト名）とポート。
• 前の手順で設定したデータベースのユーザー名（例: hyperdrive-demo）。
• そのユーザー名に対応するパスワード。
• Hyperdrive が接続するデータベース名。例: postgres。

Hyperdrive は、これらのパラメーターを組み合わせた、データベースドライバーで一般的な接続文字列形式を受け付けます。

postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

ほとんどのデータベースプロバイダーは、Hyperdrive にそのままコピー＆ペーストできる接続文字列を提供します。

node-postgres ドライバーをインストールします。

npm i pg@>8.16.3

yarn add pg@>8.16.3

pnpm add pg@>8.16.3

bun add pg@>8.16.3

TypeScript を使う場合は、型定義パッケージもインストールします。

npm i -D @types/pg

yarn add -D @types/pg

pnpm add -D @types/pg

bun add -d @types/pg

必要な Node.js 互換性フラグと Hyperdrive バインディングを、wrangler.jsonc ファイルに追加します。

{
	// required for database drivers to function
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<your-hyperdrive-id-here>"
		}
	]
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-09-20"

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"

新しい Client インスタンスを作成し、Hyperdrive の connectionString を渡します。

// filepath: src/index.ts
import { Client } from "pg";

export default {
	async fetch(
		request: Request,
		env: Env,
		ctx: ExecutionContext,
	): Promise<Response> {
		// Create a new client instance for each request. Hyperdrive maintains the
		// underlying database connection pool, so creating a new client is fast.
		const client = new Client({
			connectionString: env.HYPERDRIVE.connectionString,
		});

		try {
			// Connect to the database
			await client.connect();

			// Perform a simple query
			const result = await client.query("SELECT * FROM pg_tables");

			return Response.json({
				success: true,
				result: result.rows,
			});
		} catch (error: any) {
			console.error("Database error:", error.message);

			return new Response("Internal error occurred", { status: 500 });
		}
	},
};

• Hyperdrive の仕組み について詳しく学びます。
• よくある問題の切り分けは トラブルシューティングガイド を参照してください。
• Cloudflare Workers で使えるほかの ストレージオプション についても確認します。

@neondatabase/serverless で Neon に接続するには、次の手順に従います。

1. 接続先となる Neon データベースが必要です。Neon データベースを作成 ↗ するか、既存のデータベースから Neon にデータを読み込む ↗ こともできます。

2. Neon の SQL エディターで elements テーブルを作成します。SQL Editor を使うと、Neon Console からデータベースを直接クエリできます。

   CREATE TABLE elements (
     id INTEGER NOT NULL,
     elementName TEXT NOT NULL,
     atomicNumber INTEGER NOT NULL,
     symbol TEXT NOT NULL
   );

3. 作成したテーブルにデータを挿入します。

   INSERT INTO elements (id, elementName, atomicNumber, symbol)
   VALUES
     (1, 'Hydrogen', 1, 'H'),
     (2, 'Helium', 2, 'He'),
     (3, 'Lithium', 3, 'Li'),
     (4, 'Beryllium', 4, 'Be'),
     (5, 'Boron', 5, 'B'),
     (6, 'Carbon', 6, 'C'),
     (7, 'Nitrogen', 7, 'N'),
     (8, 'Oxygen', 8, 'O'),
     (9, 'Fluorine', 9, 'F'),
     (10, 'Neon', 10, 'Ne');

4. Worker に Neon のデータベース認証情報を設定します。

   Neon のデータベース接続文字列を、Worker のシークレットとして追加します。Neon Console ↗ の Connection Details から接続文字列を取得し、Wrangler でシークレットとして追加します。

   # Add the database connection string as a secret
   npx wrangler secret put DATABASE_URL
   # When prompted, paste your Neon database connection string

5. Worker で @neondatabase/serverless ドライバーをインストールし、データベースに接続してデータの操作を始めます。

   npmyarnpnpmbun

   npm i @neondatabase/serverless

6. 次の例は、Worker から Neon データベースへクエリする手順です。接続に必要な認証情報は、Worker のシークレットとして追加済みです。

   import { Client } from "@neondatabase/serverless";
   
   export default {
   	async fetch(request, env, ctx) {
   		const client = new Client(env.DATABASE_URL);
   		await client.connect();
   		const { rows } = await client.query("SELECT * FROM elements");
   
   		return new Response(JSON.stringify(rows));
   	},
   };

Neon の詳細は、Neon の公式ドキュメント ↗ を参照してください。