Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

Cloudflare Workers で PostgreSQL データベースに接続する

最終更新 Markdown で表示Agent セットアップ

このチュートリアルでは、Cloudflare Workers アプリケーションを作成し、TCP Sockets と Hyperdrive を使って PostgreSQL データベースに接続します。作成する Workers アプリケーションは、PostgreSQL 内の商品データベースを操作します。

前提条件

次を用意してください。

  1. まだの場合は Cloudflare アカウント ↗ に登録します。
  2. npm ↗ をインストールします。
  3. Node.js ↗ をインストールします。権限の問題を避け、Node.js のバージョンを切り替えるには、Volta ↗ や nvm ↗ などの Node バージョンマネージャーを使います。Wrangler には Node 16.17.0 以降が必要です。
  4. PostgreSQL データベースにアクセスできることを確認します。

1. Worker アプリケーションを作成する

まず、create-cloudflare CLI ↗ で新しい Worker アプリケーションを作成します。ターミナルを開き、次のコマンドを実行します。

npm create cloudflare@latest -- postgres-tutorial

この操作で create-cloudflare ↗ パッケージのインストールを求められ、セットアップウィザードが進みます。

セットアップでは、次のオプションを選びます。

  • What would you like to start with? では、Hello World example を選びます。
  • Which template would you like to use? では、Worker only を選びます。
  • Which language do you want to use? では、TypeScript を選びます。
  • Do you want to use git for version control? では、Yes を選びます。
  • Do you want to deploy your application? では、No を選びます（デプロイ前にいくつか変更します）。

デプロイを選ぶと、未ログインの場合は認証を求められ、プロジェクトがデプロイされます。デプロイしても、このチュートリアルの最後で Worker のコードを変更して再デプロイできます。

作成したディレクトリへ移動します。

cd postgres-tutorial

Node.js 互換性を有効にする

データベースドライバー（Postgres.js を含む）には Node.js 互換性 が必要です。Workers プロジェクトで設定します。

互換性日付が 2026-08-04 以降の場合、Workers と Pages プロジェクトでは nodejs_compat と nodejs_compat_v2 がデフォルトで有効になります。組み込みのランタイム API とポリフィルは、追加の設定なしで使えます。これらの互換性日付では、これらのフラグは使われません。既存プロジェクトは、互換性日付を更新するときにフラグを削除する必要はありません。

互換性日付が 2026-08-04 より前の場合は、オプトインするために Wrangler 設定ファイル に nodejs_compat 互換性フラグ を追加します。

{
	"compatibility_flags": [
		"nodejs_compat"
	]
}
compatibility_flags = [ "nodejs_compat" ]

互換性日付が 2026-08-04 以降で Node.js 互換 を完全にオフにするには、有効化フラグがあれば削除します。次に no_nodejs_compat と no_nodejs_compat_v2 の両方を追加します。設定例は Node.js 互換性フラグ を参照してください。

2. PostgreSQL 接続ライブラリを追加する

PostgreSQL データベースに接続するには、pg ライブラリが必要です。Worker アプリケーションのディレクトリで、次のコマンドを実行してインストールします。

npm i pg

次に、TypeScript コードで型チェックと自動補完を使えるよう、pg ライブラリの TypeScript 型をインストールします。

npm i -D @types/pg

3. PostgreSQL データベースへの接続を設定する

PostgreSQL データベースへの接続方法は、次の 2 つから選びます。

  1. 接続文字列を使う
  2. 明示的なパラメーターを設定する

接続文字列を使う

接続文字列には、データベースへの接続に必要な情報がすべて含まれます。次の形式の URL です。

postgresql://username:password@host:port/database

username、password、host、port、database を、PostgreSQL データベースの値に置き換えます。

接続文字列は平文で保存されないよう、シークレット として設定します。変数名の例として DB_URL を使い、wrangler secret put を実行します。

npx wrangler secret put DB_URL
➜  wrangler secret put DB_URL
-------------------------------------------------------
? Enter a secret value: › ********************
✨ Success! Uploaded secret DB_URL

シークレットを使ったローカル開発 の手順に従い、.dev.vars ファイルに DB_URL シークレットをローカル設定します。

.dev.varstoml
DB_URL="<ENTER YOUR POSTGRESQL CONNECTION STRING>"

明示的なパラメーターを設定する

各データベースパラメーターは、Cloudflare ダッシュボード または Wrangler ファイルで 環境変数 として設定します。Wrangler ファイルの設定例は次のとおりです。

{
	"vars": {
		"DB_USERNAME": "postgres",
		// Set your password by creating a secret so it is not stored as plain text
		"DB_HOST": "ep-aged-sound-175961.us-east-2.aws.neon.tech",
		"DB_PORT": 5432,
		"DB_NAME": "productsdb"
	}
}
[vars]
DB_USERNAME = "postgres"
DB_HOST = "ep-aged-sound-175961.us-east-2.aws.neon.tech"
DB_PORT = 5_432
DB_NAME = "productsdb"

パスワードを平文で保存しないよう シークレット として設定するには、wrangler secret put を使います。DB_PASSWORD は、Worker からこのシークレットを参照する変数名の例です。

npx wrangler secret put DB_PASSWORD
-------------------------------------------------------
? Enter a secret value: › ********************
✨ Success! Uploaded secret DB_PASSWORD

4. Worker から PostgreSQL データベースに接続する

Worker のメインファイル（例: worker.ts）を開き、pg ライブラリから Client クラスをインポートします。

import { Client } from "pg";

fetch イベントハンドラーで、接続文字列または明示的なパラメーターのどちらかで PostgreSQL データベースに接続します。

接続文字列を使う

// create a new Client instance using the connection string
const sql = new Client({ connectionString: env.DB_URL });
// connect to the PostgreSQL database
await sql.connect();

明示的なパラメーターを設定する

// create a new Client instance using explicit parameters
const sql = new Client({
	username: env.DB_USERNAME,
	password: env.DB_PASSWORD,
	host: env.DB_HOST,
	port: env.DB_PORT,
	database: env.DB_NAME,
	ssl: true, // Enable SSL for secure connections
});
// connect to the PostgreSQL database
await sql.connect();

5. 商品データベースを操作する

商品データベースの操作例として、リクエスト受信時に products テーブルをクエリし、データを取得します。

worker.ts の既存コードを、次のコードに置き換えます。

import { Client } from "pg";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new Client instance using the connection string
		// or explicit parameters as shown in the previous steps.
		// Here, we are using the connection string method.
		const sql = new Client({
			connectionString: env.DB_URL,
		});
        // Connect to the PostgreSQL database
        await sql.connect();

        // Query the products table
        const result = await sql.query("SELECT * FROM products");

        // Return the result as JSON
        return new Response(JSON.stringify(result.rows), {
            headers: {
                "Content-Type": "application/json",
            },
        });
	},
} satisfies ExportedHandler<Env>;

このコードは、Worker アプリケーション内で PostgreSQL データベースに接続し、products テーブルをクエリして、結果を JSON レスポンスとして返します。

6. Worker をデプロイする

次のコマンドで Worker をデプロイします。

npx wrangler deploy

アプリケーションは <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev で公開されます。

デプロイ後は、Cloudflare Worker から PostgreSQL の商品データベースを操作できます。Worker の URL へリクエストがあると、products テーブルからデータを取得し、JSON レスポンスとして返します。取得するデータに合わせてクエリを変更できます。

7. 商品データベースに新しい行を挿入する

products テーブルに新しい行を挿入するには、POST リクエストを処理する API エンドポイントを Worker に追加します。JSON ペイロード付きの POST リクエストを受け取ると、Worker は指定されたデータで products テーブルに新しい行を挿入します。

products テーブルには id、name、description、price 列があるとします。

worker.ts の fetch イベントハンドラー内、既存のクエリコードの前に、次のコードを追加します。

import { Client } from "pg";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new Client instance using the connection string
		// or explicit parameters as shown in the previous steps.
		// Here, we are using the connection string method.
		const sql = new Client({
			connectionString: env.DB_URL,
		});
        // Connect to the PostgreSQL database
        await sql.connect();

        const url = new URL(request.url);
        if (request.method === "POST" && url.pathname === "/products") {
            // Parse the request's JSON payload
            const productData = (await request.json()) as {
                name: string;
                description: string;
                price: number;
            };

            const name = productData.name,
                description = productData.description,
                price = productData.price;

            // Insert the new product into the products table
            const insertResult = await sql.query(
                `INSERT INTO products(name, description, price) VALUES($1, $2, $3)
    RETURNING *`,
                [name, description, price],
            );

            // Return the inserted row as JSON
            return new Response(JSON.stringify(insertResult.rows), {
                headers: { "Content-Type": "application/json" },
            });
        }

        // Query the products table
        const result = await sql.query("SELECT * FROM products");

        // Return the result as JSON
        return new Response(JSON.stringify(result.rows), {
            headers: {
                "Content-Type": "application/json",
            },
        });
	},
} satisfies ExportedHandler<Env>;

このコードは次を行います。

  1. リクエストが POST で、URL パスが /products かを確認します。
  2. リクエストの JSON ペイロードを解析します。
  3. 受け取った商品データで INSERT SQL クエリを組み立てます。
  4. クエリを実行し、products テーブルに新しい行を挿入します。
  5. 挿入した行を JSON レスポンスとして返します。

これで、Worker の URL の /products パスへ JSON ペイロード付きの POST リクエストを送ると、Worker は指定データで products テーブルに新しい行を挿入します。/ へのリクエストでは、データベース内の全商品を返します。

変更後、次のコマンドで Worker を再デプロイします。

npx wrangler deploy

Cloudflare Worker から products テーブルへ新しい行を挿入できるようになりました。動作確認するには、Worker の URL の /products パスへ、新しい商品データを含む JSON ペイロード付きの POST リクエストを送ります。

{
	"name": "Sample Product",
	"description": "This is a sample product",
	"price": 19.99
}

Cloudflare Worker から PostgreSQL データベースに接続し、商品テーブルの取得と新しい行の挿入を処理できるようになりました。

8. Hyperdrive でクエリを高速化する

PostgreSQL データベースの接続文字列を使って、Hyperdrive 設定を作成します。

npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --caching-disabled

このコマンドは、Hyperdrive バインディング に使う Hyperdrive 設定の id を出力します。Wrangler ファイルに id を指定してバインディングを設定します。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "hyperdrive-example",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Pasted from the output of `wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string=[...]` above.
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"
		}
	]
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "hyperdrive-example"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-09-20"
compatibility_flags = [ "nodejs_compat" ]

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"

次のコマンドで Hyperdrive バインディングの型を生成します。

npx wrangler types

Worker コード内の既存の接続文字列を、Hyperdrive の接続文字列に置き換えます。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const sql = new Client({connectionString: env.HYPERDRIVE.connectionString})

		const url = new URL(request.url);

		//rest of the routes and database queries
	},
} satisfies ExportedHandler<Env>;

9. Worker を再デプロイする

次のコマンドで Worker をデプロイします。

npx wrangler deploy

Worker アプリケーションは <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev で公開され、Hyperdrive を使います。Hyperdrive は接続をプールし、リクエストを世界中でキャッシュして、データベースクエリを高速化します。

次のステップ

データベースと Workers をさらに使うには、チュートリアル と Databases のドキュメント を参照してください。

質問がある場合、サポートが必要な場合、プロジェクトを共有したい場合は、Discord ↗ の Cloudflare Developer コミュニティで開発者や Cloudflare チームとつながれます。

役に立ちましたか？