INTEGRITY Документация

← Cloudflare D1 / d1

Workers Binding API

SQL-запросы к базе данных D1 можно выполнять из Worker с помощью Worker Binding API. Для этого выполните следующие шаги:

  1. Привязка базы данных D1.
  2. Подготовка оператора.
  3. Выполнение prepared statement.
  4. Проанализируйте возвращаемый объект (при необходимости).

См. соответствующие разделы документации по API.

Поддержка TypeScript

D1 Worker Bindings API полностью типизирован благодаря runtime-типам, генерируемым при выполнении wrangler types пакет, а также поддерживает обобщённые типы ↗ как часть своего TypeScript API. Обобщённый тип (generic) позволяет указать необязательный type parameter чтобы функция понимала тип обрабатываемых данных.

При использовании методов операторов запросов D1PreparedStatement::run, D1PreparedStatement::raw и D1PreparedStatement::first, вы можете указать тип, представляющий каждую строку базы данных. API D1 будет возвращает объект результата с правильным типом.

Например, если указать OrderRow тип в качестве параметра типа для D1PreparedStatement::run вернёт типизированный 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 автоматически преобразует поддерживаемые типы JavaScript (включая TypeScript), переданные в качестве параметров через Workers Binding API, в соответствующие типы D1 1. Это преобразование необратимо и выполняется только в одну сторону. Это означает, что при чтении сохранённых значений в коде вы получите преобразованные значения, а не исходные, которые были вставлены.

Преобразование типов при записи выполняется следующим образом:

JavaScript (запись) D1 JavaScript (чтение)
null NULL null
Число REAL Число
Число 2 INTEGER Число
String TEXT String
Boolean 3 INTEGER Число (0,1)
ArrayBuffer BLOB Array 4
ArrayBuffer View BLOB Array 4
undefined Не поддерживается. 5 -

1 типы D1 соответствуют базовым SQLite типы ↗.

2 D1 поддерживает 64-битные целые числа со знаком INTEGER значения внутри системы, однако BigInt ↗ пока не поддерживаются в API. Целые числа JavaScript безопасны до Number.MAX_SAFE_INTEGER ↗.

3 Значения типа boolean будут приведены к INTEGER тип, где 1 это TRUE и 0 это FALSE.

4 ArrayBuffer и ArrayBuffer представления ↗ преобразуются с помощью Array.from ↗.

5 Запросы с undefined значения вернут D1_TYPE_ERROR.

API playground

Песочница D1 Worker Binding API представляет собой index.js файл, где можно протестировать каждый из описанных Worker Binding API для D1. Файл строится на основе конечного состояния Начало работы код.

Это можно использовать вместе с документацией по API, чтобы лучше понять принцип работы каждого API.

Выполните шаги, чтобы настроить свой API playground.

1. Пройдите руководство Get started

Выполните Начало работы руководство. Убедитесь, что используете 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.