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 类型作为类型参数，将返回类型化的 Array<OrderRow> 对象，而不是默认的 Record<string, unknown> 类型：

// 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 (write)	D1	JavaScript (read)
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	Not supported. ⁵	-

¹ D1 types correspond to the underlying SQLite types ↗.

² D1 supports 64-bit signed INTEGER values internally, however BigInts ↗ are not currently supported in the API yet. JavaScript integers are safe up to Number.MAX_SAFE_INTEGER ↗.

³ Booleans will be cast to an INTEGER type where 1 is TRUE and 0 is FALSE.

⁴ ArrayBuffer and ArrayBuffer views ↗ are converted using Array.from ↗.

⁵ Queries with undefined values will return a D1_TYPE_ERROR.

API 演练场

D1 Worker Binding API 演练场是一个 index.js 文件，您可以在其中测试 D1 的每个已记录 Worker Binding API。该文件基于快速入门代码的最终状态构建。

您可以将其与 API 文档一起使用，以更好地理解每个 API 的工作原理。

按照以下步骤设置 API 演练场。

1. 完成快速入门教程

完成快速入门教程。确保使用 JavaScript 而非 TypeScript。

2. 修改 `index.js` 的内容

将 index.js 文件的内容替换为以下代码，以查看每个 API 的效果。

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

运行 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。