npm install hono

本指南指导您:

  • 使用Cloudflare的本机无服务器SQL数据库D1创建您的第一个数据库。

  • 创建模式并通过命令行查询数据库。

  • 连接一个Cloudflare工作人员到您的D1数据库以编程方式查询您的D1数据库。

您可以通过CLI或Cloudflare控制面板执行这些任务。

备注

如果您已经有一个现有的Worker和一个现有的D1数据库，请按照本教程从3.将Worker绑定到D1数据库。

先决条件

  1. 注册一个Cloudflare帐户↗。

  2. 安装Node.js↗。

Node.js版本管理器

1.创建一个工人

创建一个新的Worker作为查询数据库的方法。

  1. 创建一个名为的新项目d1-tutorial通过运行:

    终端窗口npm create cloudflare@latest -- d1-tutorial对于 “设置”，请选择以下选项:

    • 用于_你想从什么开始？_,选择Hello World example。
    • 用于_您要使用哪个模板？_,选择Hello World Worker。
    • 用于_您想使用哪种语言？_,选择TypeScript。
    • 用于_你想使用git进行版本控制吗？_,选择Yes。
    • 用于_是否要部署应用程序？_,选择No(我们将在部署之前进行一些更改)。

    这将创建一个新的d1-tutorial目录，如下图所示。

    • 目录d1-tutorial
      • 目录node_modules/
      • 目录试验/
      • 目录src
        • index.ts
      • package-lock.json
      • package.json
      • testconfig.json
      • vitest.config.mts
      • worker-configuration.d.ts
      • 牧马人.托姆

    您的新d1-tutorial目录包括:

    • A"Hello World" 工人在index.ts。

    • Awrangler.toml配置文件。wrangler.toml是你的d1-tutorialWorker访问您的D1数据库。

备注

如果您熟悉Cloudflare Workers，或者在持续集成 (CI) 环境中初始化项目，请通过设置CI=true作为运行时的环境变量create cloudflare@latest。

例如:CI=true npm create cloudflare@latest d1-tutorial --type=simple --git --ts --deploy=false创建一个基本的 “Hello World” 项目。

2.创建数据库

D1数据库在概念上类似于许多其他数据库: 数据库可以包含一个或多个表、查询这些表的能力以及可选的索引。D1使用熟悉的SQL查询语言↗(由SQLite使用)。

创建第一个D1数据库:

  1. 更改为您刚刚为Workers项目创建的目录:终端窗口cd d1-tutorial

  2. 运行以下wrangler d1命令并为您的数据库命名。在本教程中，数据库名为prod-d1-tutorial:终端窗口npx wrangler d1 create prod-d1-tutorial``✅ Successfully created DB 'prod-d1-tutorial'[[d1_databases]]binding = "DB" # available in your Worker on env.DBdatabase_name = "prod-d1-tutorial"database_id = "<unique-ID-for-your-database>"

这将创建一个新的D1数据库并输出装订下一步需要配置。

备注

的wrangler命令行界面是Cloudflare的工具，用于在终端中管理和部署Workers应用程序和D1数据库。它是在你使用的时候安装的npm create cloudflare@latest初始化您的新项目。

备注

作为参考，一个好的数据库名称:

  • 使用小于32个字符的ASCII字符组合，并使用破折号 (-) 代替空格。

  • 描述用例和环境。例如，“staging-db-web” 或 “production-db-backend”。

  • 仅描述数据库，并且不在代码中直接引用。

3.将Worker绑定到D1数据库

您必须为Worker创建绑定才能连接到D1数据库。绑定允许您的工作人员访问Cloudflare开发人员平台上的资源 (如D1)。

要将D1数据库绑定到您的工作人员:

您可以通过更新您的wrangler.toml文件。

  1. 复制从获得的行步骤2从你的终端。

  2. 将它们添加到您的wrangler.toml文件。

    [[d1_databases]]binding = "DB" # available in your Worker on env.DBdatabase_name = "prod-d1-tutorial"database_id = "<unique-ID-for-your-database>"具体而言:

    • 为设置的值 (字符串)binding是绑定名称,并用于在您的Worker中引用此数据库。在本教程中，将您的绑定命名为DB。

    • 绑定名称必须为有效的JavaScript变量名↗。例如，binding = "MY_DB"或binding = "productionDB"都将是绑定的有效名称。

    • 您的绑定在您的工作人员中可用，位于env.<BINDING_NAME>和D1客户端API在此绑定上暴露。

备注

当您执行wrangler d1 create命令，则会自动安装客户端API包 (它实现D1 API和数据库类)。有关D1客户端API的详细信息，请参阅D1客户端API。

您还可以将D1数据库绑定到Pages函数。有关更多信息，请参考D1的函数绑定。

4.对D1数据库运行查询

配置D1数据库

与wrangler.toml正确配置，设置您的数据库。使用示例schema.sql下面的文件来初始化您的数据库。

  1. 复制以下代码并将其保存为schema.sql文件中的d1-tutorial您在步骤1中创建的工作目录:DROP TABLE IF EXISTS Customers;CREATE TABLE IF NOT EXISTS Customers (CustomerId INTEGER PRIMARY KEY, CompanyName TEXT, ContactName TEXT);INSERT INTO Customers (CustomerID, CompanyName, ContactName) VALUES (1, 'Alfreds Futterkiste', 'Maria Anders'), (4, 'Around the Horn', 'Thomas Hardy'), (11, 'Bs Beverages', 'Victoria Ashworth'), (13, 'Bs Beverages', 'Random Name');

  2. 初始化数据库以首先在本地运行和测试。通过运行以下命令引导您的新D1数据库:终端窗口npx wrangler d1 execute prod-d1-tutorial --local --file=./schema.sql

  3. 通过运行来验证您的数据是否在数据库中:终端窗口npx wrangler d1 execute prod-d1-tutorial --local --command="SELECT * FROM Customers"``🌀 Mapping SQL input into an array of statements🌀 Executing on local database production-db-backend (5f092302-3fbd-4247-a873-bf1afc5150b) from .wrangler/state/v3/d1:┌────────────┬─────────────────────┬───────────────────┐│ CustomerId │ CompanyName │ ContactName │├────────────┼─────────────────────┼───────────────────┤│ 1 │ Alfreds Futterkiste │ Maria Anders │├────────────┼─────────────────────┼───────────────────┤│ 4 │ Around the Horn │ Thomas Hardy │├────────────┼─────────────────────┼───────────────────┤│ 11 │ Bs Beverages │ Victoria Ashworth │├────────────┼─────────────────────┼───────────────────┤│ 13 │ Bs Beverages │ Random Name │└────────────┴─────────────────────┴───────────────────┘

在Worker中编写查询

设置数据库后，从Worker中运行SQL查询。

  1. 导航到您的d1-tutorialWorker并打开index.ts文件。的index.ts文件是您配置Worker与d1的交互的位置。

  2. 清除的内容index.ts。

  3. 将以下代码段粘贴到您的index.ts文件:

    index.jsexport default { async fetch(request, env) { const { pathname } = new URL(request.url); if (pathname === "/api/beverages") { // If you did not use `DB` as your binding name, change it here const { results } = await env.DB.prepare( "SELECT * FROM Customers WHERE CompanyName = ?", ) .bind("Bs Beverages") .all(); return Response.json(results); } return new Response( "Call /api/beverages to see everyone who works at Bs Beverages", ); },};在上面的代码中，您:

    1. 在TypeScript代码中定义与D1数据库的绑定。此绑定与binding您在中设置的值wrangler.toml下[[d1_databases]]。

    2. 使用查询您的数据库env.DB.prepare发出一个已准备的查询带有占位符 (?在查询中)。

    3. 呼叫bind()安全可靠地将值绑定到该占位符。在实际应用程序中，您将允许用户定义CompanyName他们想列出结果。使用bind()防止用户对您的应用程序执行任意SQL (称为 “SQL注入”) 并删除或以其他方式修改您的数据库。

    4. 通过调用执行查询all()返回所有行 (如果查询返回none，则返回none)。

    5. 以JSON格式返回您的查询结果 (如果有)Response.json(results)。

配置工作线程后，您可以在全局部署之前在本地测试项目。

5.部署数据库

在Cloudflare的全球网络上部署数据库。

要使用Wrangler将Worker部署到生产环境，您必须首先重复数据库配置替换后的步骤--local标志与--remote标记以提供要读取的工作人员数据。这将创建数据库表并将数据导入到数据库的生产版本中。

  1. 引导您的数据库与schema.sql在步骤4中创建的文件:终端窗口npx wrangler d1 execute prod-d1-tutorial --remote --file=./schema.sql

  2. 通过运行以下操作来验证数据是否处于生产状态:终端窗口npx wrangler d1 execute prod-d1-tutorial --remote --command="SELECT * FROM Customers"

  3. 部署您的工作人员以使您的项目可在Internet上访问。运行时间:终端窗口npx wrangler deploy``Outputs: https://d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev您现在可以访问新创建的项目的URL来查询您的实时数据库。例如，如果新Worker的URL为d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev,访问https://d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev/api/beverages向您的工作人员发送直接查询您的实时数据库的请求。

  4. 测试数据库是否成功运行。添加/api/beverages到提供的牧马人URL。例如，https://d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev/api/beverages。

6. (可选) 与牧马人本地开发

如果您将D1与Wrangler一起使用，则可以在本地测试数据库。在您的项目目录中:

  1. 运行wrangler dev:终端窗口npx wrangler dev当你运行wrangler dev,牧马人提供了一个URL (很可能localhost:8787) 审查你的工人。

  2. 转到URL。页面显示Call /api/beverages to see everyone who works at Bs Beverages。

  3. 测试数据库是否成功运行。添加/api/beverages到提供的牧马人URL。例如，localhost:8787/api/beverages。

如果成功，浏览器将显示您的数据。

备注

如果您使用Wrangler，则只能在本地开发。您无法通过Cloudflare仪表板进行本地开发。

7. (可选) 删除您的数据库

删除数据库:

运行时间:终端窗口

1
npx wrangler d1 delete prod-d1-tutorial

如果您想删除您的员工:

运行时间:终端窗口

1
npx wrangler delete d1-tutorial

摘要

在本教程中，您有:

  • 已创建D1数据库

  • 创建了一个Worker来访问该数据库

  • 在全球部署您的项目

后续步骤

如果您有任何功能请求或发现任何错误，请通过加入Discord上的Cloudflare开发人员社区↗。