Workers Binding API

Worker Binding API を使うと、Worker から D1 データベースに対して SQL クエリを実行できます。次の手順で行います。

API の説明は、該当する各節を参照してください。

TypeScript のサポート

D1 Worker Bindings API は、wrangler types で生成されるランタイム型によって完全に型付けされ、TypeScript API の一部としてジェネリック型 ↗ もサポートします。ジェネリック型を使うと、関数が扱うデータの型を理解できるよう、任意の type parameter（型パラメーター）を渡せます。

クエリステートメントのメソッド D1PreparedStatement::run、D1PreparedStatement::raw、D1PreparedStatement::first を使うとき、各データベース行を表す型を渡せます。D1 の API は、正しい型の結果オブジェクトを返します。

たとえば、D1PreparedStatement::run に型パラメーターとして OrderRow 型を渡すと、デフォルトの Record<string, unknown> ではなく、型付きの Array<OrderRow> オブジェクトが返ります。

// Row definition
type OrderRow = {
	Id: string;
	CustomerName: string;
	OrderDate: number;
};

// Elsewhere in your application
// env.MY_DB is the D1 database binding from your Wrangler configuration file
const result = await env.MY_DB.prepare(
	"SELECT Id, CustomerName, OrderDate FROM [Order] ORDER BY ShippedDate DESC LIMIT 100",
).run<OrderRow>();

型変換

D1 は、Workers Binding API 経由でパラメーターとして渡された、対応する JavaScript（TypeScript を含む）の型を、関連する D1 の型 ¹ に自動変換します。この変換は永続的で、一方向のみです。つまり、書き込んだ値をコードで読み戻すと、元の挿入値ではなく、変換後の値が返ります。

書き込み時の型変換は次のとおりです。

JavaScript（書き込み）	D1	JavaScript（読み取り）
null	`NULL`	null
Number	`REAL`	Number
Number ²	`INTEGER`	Number
String	`TEXT`	String
Boolean ³	`INTEGER`	Number (`0`,`1`)
ArrayBuffer	`BLOB`	Array ⁴
ArrayBuffer View	`BLOB`	Array ⁴
undefined	未対応です。⁵	-

¹ D1 の型は、基盤となる SQLite の型 ↗ に対応します。

² D1 は内部で 64 ビット符号付き INTEGER 値をサポートしますが、 BigInts ↗ は現時点では API で未対応です。JavaScript の整数は Number.MAX_SAFE_INTEGER ↗ まで安全です。

³ Boolean は INTEGER 型にキャストされ、1 が TRUE、 0 が FALSE です。

⁴ ArrayBuffer と ArrayBuffer views ↗ は Array.from ↗ で変換されます。

⁵ undefined 値を含むクエリは D1_TYPE_ERROR を返します。

API プレイグラウンド

D1 Worker Binding API プレイグラウンドは、D1 向けにドキュメント化された各 Worker Binding API を試せる index.js ファイルです。このファイルは、使ってみるの完了時点のコードから組み立てます。

API ドキュメントとあわせて使うと、各 API の動きを把握しやすくなります。

次の手順で API プレイグラウンドをセットアップします。

1. 「使ってみる」チュートリアルを完了する

使ってみるチュートリアルを完了します。TypeScript ではなく JavaScript を使ってください。

2. `index.js` の内容を変更する

各 API の効果を確認するため、index.js の内容を次のコードに置き換えます。

index.js

// D1 API Playground - Test each D1 Worker Binding API method
// Change the URL pathname to test different methods (e.g., /RUN, /RAW, /FIRST)
export default {
	async fetch(request, env) {
	  const { pathname } = new URL(request.url);

		// Sample data for testing
		const companyName1 = `Bs Beverages`;
		const companyName2 = `Around the Horn`;

		// Prepare reusable statements
		const stmt = env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);
		const stmtMulti = env.DB.prepare(`SELECT * FROM Customers; SELECT * FROM Customers WHERE CompanyName = ?`);
		const session = env.DB.withSession("first-primary")
		const sessionStmt = session.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);

      // Test D1PreparedStatement::run - returns full D1Result object
      if (pathname === `/RUN`){
    	const returnValue = await stmt.bind(companyName1).run();
    	return Response.json(returnValue);

      // Test D1PreparedStatement::raw - returns array of arrays
    } else if (pathname === `/RAW`){
    	const returnValue = await stmt.bind(companyName1).raw();
    	return Response.json(returnValue);

      // Test D1PreparedStatement::first - returns first row only
    } else if (pathname === `/FIRST`){
    	const returnValue = await stmt.bind(companyName1).first();
    	return Response.json(returnValue);

      // Test D1Database::batch - execute multiple statements
    } else if (pathname === `/BATCH`) {
    	const batchResult = await env.DB.batch([
    		stmt.bind(companyName1),
    		stmt.bind(companyName2)
    	]);
    	return Response.json(batchResult);

      // Test D1Database::exec - execute raw SQL without parameters
    } else if (pathname === `/EXEC`){
    	const returnValue = await env.DB.exec(`SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"`);
    	return Response.json(returnValue);

      // Test D1 Sessions API with read replication
    } else if (pathname === `/WITHSESSION`){
    	const returnValue = await sessionStmt.bind(companyName1).run();
    	console.log("You're now using D1 Sessions!")
    	return Response.json(returnValue);
    }

      // Default response with instructions
      return new Response(
    	`Welcome to the D1 API Playground!
    	\nChange the URL to test the various methods inside your index.js file.`,
      );
    },

};

3. Worker をデプロイする

手順 1 で作成したチュートリアルのディレクトリに移動します。

npx wrangler deploy を実行します。

npx wrangler deploy

⛅️ wrangler 3.112.0
--------------------

Total Upload: 1.90 KiB / gzip: 0.59 KiB
Your worker has access to the following bindings:
- D1 Databases:
	- DB: DATABASE_NAME (<DATABASE_ID>)
Uploaded WORKER_NAME (7.01 sec)
Deployed WORKER_NAME triggers (1.25 sec)
	https://jun-d1-rr.d1-sandbox.workers.dev
Current Version ID: VERSION_ID

表示されたアドレスをブラウザーで開きます。

4. API を試す

URL を変えて、各種 D1 Worker Binding API を試します。