INTEGRITY Dokumentace

← Cloudflare D1 / d1

Workers Binding API

SQL dotazy do databáze D1 můžete z Workeru spouštět pomocí Worker Binding API. Postupujte podle následujících kroků:

  1. Navázání databáze D1.
  2. Příprava příkazu.
  3. Spusťte prepared statement.
  4. Analyzujte návratový objekt (v případě potřeby).

Příslušné části najdete v dokumentaci API.

Podpora TypeScript

D1 Worker Bindings API je plně typované díky runtime typům generovaným spuštěním wrangler types balíček a také podporuje generické typy ↗ jako součást svého TypeScript API. Obecný typ (generic) umožňuje zadat volitelný type parameter aby funkce rozuměla typu dat, se kterými pracuje.

Při použití metod pro provádění dotazů D1PreparedStatement::run, D1PreparedStatement::raw a D1PreparedStatement::first, můžete zadat typ představující jednotlivé řádky databáze. API D1 vrátí objekt výsledku se správným typem.

Pokud například zadáte OrderRow typ jako typový parametr pro D1PreparedStatement::run vrátí typovaný Array<OrderRow> objekt namísto výchozího Record<string, unknown> typ:

// 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>();

Konverze typů

D1 automaticky převádí podporované typy JavaScriptu (včetně TypeScriptu) předané jako parametry přes Workers Binding API na odpovídající typy D1 1. Tato konverze je trvalá a jednosměrná. To znamená, že při zpětném čtení zapsaných hodnot ve vašem kódu získáte konvertované hodnoty, nikoli hodnoty, které jste původně vložili.

Převod typů při zápisu probíhá následovně:

JavaScript (zápis) D1 JavaScript (čtení)
null NULL null
Číslo REAL Číslo
Číslo 2 INTEGER Číslo
Řetězec TEXT Řetězec
Boolean 3 INTEGER Číslo (0,1)
ArrayBuffer BLOB Array 4
ArrayBuffer View BLOB Array 4
undefined Nepodporováno. 5 -

1 typy D1 odpovídají podkladovým SQLite typy ↗.

2 D1 podporuje 64bitová celá čísla se znaménkem INTEGER hodnoty interně, nicméně BigInt ↗ zatím nejsou v API podporovány. Celá čísla JavaScriptu jsou bezpečná do Number.MAX_SAFE_INTEGER ↗.

3 Hodnoty typu boolean budou převedeny na INTEGER typ, kde 1 je TRUE a 0 je FALSE.

4 ArrayBuffer a ArrayBuffer pohledy ↗ se převádí pomocí Array.from ↗.

5 Dotazy s undefined hodnoty vrátí D1_TYPE_ERROR.

API playground

D1 Worker Binding API playground je index.js soubor, kde můžete otestovat každé z dokumentovaných Worker Binding API pro D1. Tento soubor vychází z konečného stavu Začínáme kód.

Spolu s dokumentací API vám to pomůže lépe pochopit fungování jednotlivých API.

Postupujte podle kroků a nastavte si API playground.

1. Dokončete tutoriál Get started

Dokončete Začínáme tutoriál. Ujistěte se, že používáte JavaScript místo TypeScriptu.

2. Upravte obsah index.js

Nahraďte obsah svého index.js soubor kódem níže a podívejte se na účinek každého 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. Nasaďte Worker

  1. Přejděte do adresáře tutoriálu, který jste vytvořili podle kroku 1.
  2. Spustit 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. Otevře prohlížeč na zadané adrese.

4. Otestujte API

Změňte URL adresu a vyzkoušejte různá API pro vazbu D1 Worker.