跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

Workers Binding API

最后更新 查看 MarkdownAgent 设置

您可以使用 Worker Binding API 从 Worker 对 D1 数据库执行 SQL 查询。为此,您可以执行以下步骤:

  1. 绑定 D1 数据库。
  2. 准备语句。
  3. 运行预编译语句。
  4. 分析返回对象(如有必要)。

请参阅相关部分了解 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 类型 1。 此转换是永久且单向的。这意味着在代码中读回写入的值时,您将获得转换后的值,而不是原始插入的值。

写入期间的类型转换如下:

JavaScript (write) D1 JavaScript (read)
null NULL null
Number REAL Number
Number 2 INTEGER Number
String TEXT String
Boolean 3 INTEGER Number (0,1)
ArrayBuffer BLOB Array 4
ArrayBuffer View BLOB Array 4
undefined Not supported. 5 -

1 D1 类型对应底层的 SQLite 类型 ↗。

2 D1 在内部支持 64 位有符号 INTEGER 值,但 API 目前尚不支持 BigInt ↗。 JavaScript 整数在 Number.MAX_SAFE_INTEGER ↗ 范围内是安全的。

3 Boolean 会转换为 INTEGER 类型,其中 1 为 TRUE,0 为 FALSE。

4 ArrayBuffer 和 ArrayBuffer 视图 ↗ 会使用 Array.from ↗ 进行转换。

5 查询中包含 undefined 值时会返回 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

  1. 导航到按照步骤 1 创建的教程目录。
  2. 运行 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
  3. 在浏览器中打开指定地址。

4. 测试 API

更改 URL 以测试各种 D1 Worker Binding API。

这篇文档对您有帮助吗?