Python Workers から D1 をクエリする

Cloudflare Workers プラットフォームは TypeScript、JavaScript、Rust、Python を含む複数の言語に対応しています。このガイドでは、Python から D1 データベースをクエリし、アプリケーションをグローバルにデプロイする方法を示します。

前提条件

始める前に、次を確認してください。

TypeScript と JavaScript 向けの D1 チュートリアルを確認し、D1 データベースの作成と Workers プロジェクトの設定 を学びます。
Python 言語ガイドを参照し、Workers プラットフォームでの Python 対応のしくみを理解します。
Python 言語の基本を把握していること。

Cloudflare Workers が初めての場合は、この例を続ける前にはじめにガイドを参照してください。

Python からクエリする

この例では、既存の D1 データベースがあることを前提とします。Python Worker がデータベースをクエリできるようにするには、まず Worker と D1 データベースの間にバインディングを作り、Wrangler 設定ファイルで定義します。

D1 データベースの database_name と database_id が必要です。wrangler CLI で新しいデータベースを作成するか、既存データベースの ID を次のように取得できます。

Create a databasesh

npx wrangler d1 create my-first-db

Retrieve a database IDsh

npx wrangler d1 info some-existing-db

# ┌───────────────────┬──────────────────────────────────────┐
# │                   │ c89db32e-83f4-4e62-8cd7-7c8f97659029 │
# ├───────────────────┼──────────────────────────────────────┤
# │ name              │ db-enam                              │
# ├───────────────────┼──────────────────────────────────────┤
# │ created_at        │ 2023-06-12T16:52:03.071Z             │
# └───────────────────┴──────────────────────────────────────┘

1. バインディングを設定する

Wrangler ファイルに新しい [[d1_databases]] 設定ブロックを作り、database_name と database_id を、クエリしたい D1 データベースの名前と ID に設定します。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "python-and-d1",
	"main": "src/entry.py",
	"compatibility_flags": [ // Required for Python Workers
		"python_workers"
	],
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"d1_databases": [
		{
			"binding": "DB", // This will be how you refer to your database in your Worker
			"database_name": "YOUR_DATABASE_NAME",
			"database_id": "YOUR_DATABASE_ID"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "python-and-d1"
main = "src/entry.py"
compatibility_flags = [ "python_workers" ]
# Set this to today's date
compatibility_date = "2026-09-20"

[[d1_databases]]
binding = "DB"
database_name = "YOUR_DATABASE_NAME"
database_id = "YOUR_DATABASE_ID"

binding の値は、Worker 内からデータベースを参照する方法です。これを変更した場合は、Worker スクリプト内でも変更する必要があります。

2. Python Worker を作成する

Python Worker を作成するには、Wrangler ファイルの main の値に合わせて、次の内容で空のファイル src/entry.py を作成します。

from workers import Response, WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        # Do anything else you'd like on request here!

        try:
            # Query D1 - we'll list all tables in our database in this example
            results = await self.env.DB.prepare("PRAGMA table_list").run()
            # Return a JSON response
            return Response.json(results)
        except Exception as e:
            return Response.json({"error": "Database query failed"}, status=500)

Wrangler ファイルの binding の値は、Python コード内の変数名と正確に一致する必要があります。この例では DB バインディング経由でデータベースを参照し、await self.env.DB.prepare(...) でこのバインディングをクエリします。

Python Worker は次のように直接デプロイできます。

npx wrangler deploy

# Example output
#
# Your worker has access to the following bindings:
# - D1 Databases:
#   - DB: db-enam (c89db32e-83f4-4e62-8cd7-7c8f97659029)
# Total Upload: 0.18 KiB / gzip: 0.17 KiB
# Uploaded python-and-d1 (4.93 sec)
# Published python-and-d1 (0.51 sec)
#   https://python-and-d1.YOUR_SUBDOMAIN.workers.dev
# Current Deployment ID: 80b72e19-da82-4465-83a2-c12fb11ccc72

Worker は https://python-and-d1.YOUR_SUBDOMAIN.workers.dev で利用できます。

デプロイでエラーが出た場合は次を確認します。

Wrangler 設定ファイルに、有効な D1 データベースの database_id と database_name が設定されていること。
Python に必要な compatibility_flags = ["python_workers"] が Wrangler 設定ファイルに設定されていること。
エラーコードの一覧を確認し、コードが捕捉されない例外を投げていないこと。

次のステップ

Workers Python ドキュメントを参照し、Workers で Python を使う方法を学びます。
D1 Workers Binding API と D1 データベースのクエリ方法を確認します。
D1 データベースへのデータのインポート方法を学びます。