← Cloudflare D1 / d1 / worker-api

D1 Database

Pro práci s databází D1 z Workeru k ní musíte přistupovat prostřednictvím environment bindings poskytnutých Workeru (env).

async fetch(request, env) {
	// D1 database is 'env.DB', where "DB" is the binding name from the Wrangler configuration file.
}

from workers import WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        # D1 database is 'self.env.DB', where "DB" is the binding name from the Wrangler configuration file.
        pass

Binding D1 má typ D1Database, a podporuje řadu metod, jak je uvedeno níže.

Metody

`prepare()`

Připraví příkaz dotazu k pozdějšímu spuštění.

const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);

some_variable = "Bs Beverages"
stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(some_variable)

Parametry

query: String Povinné
- SQL dotaz, který chcete na databázi spustit.

Návratové hodnoty

D1PreparedStatement: Object
- Objekt, který obsahuje pouze metody. Další informace najdete v Metody prepared statementu.

Pokyny

Můžete použít bind metoda pro dynamické navázání hodnoty do příkazu dotazu, jak je uvedeno níže.

Příklad statického příkazu bez použití bind:

const stmt = db
	.prepare("SELECT * FROM Customers WHERE CompanyName = 'Alfreds Futterkiste' AND CustomerId = 1")

stmt = db.prepare("SELECT * FROM Customers WHERE CompanyName = 'Alfreds Futterkiste' AND CustomerId = 1")

Příklad seřazeného příkazu s použitím bind:

const stmt = db
	.prepare("SELECT * FROM Customers WHERE CompanyName = ? AND CustomerId = ?")
	.bind("Alfreds Futterkiste", 1);

stmt = db.prepare("SELECT * FROM Customers WHERE CompanyName = ? AND CustomerId = ?").bind("Alfreds Futterkiste", 1)

Viz bind dokumentace metody s dalšími informacemi.

`batch()`

Odešle více SQL příkazů v rámci jednoho volání databáze. To může mít výrazný vliv na výkon, protože snižuje latenci síťových přenosů k D1. D1 pracuje v režimu auto-commit. Naše implementace zaručuje, že se každý příkaz v seznamu provede a potvrdí postupně, nikoli souběžně.

Dávkové příkazy jsou Transakce SQL ↗. Pokud se některý příkaz v sekvenci nezdaří, vrátí se chyba pro tento konkrétní příkaz a celá sekvence se přeruší nebo vrátí zpět.

Pro odeslání dávkových příkazů zadejte D1Database::batch seznam prepared statements a získat výsledky ve stejném pořadí.

const companyName1 = `Bs Beverages`;
const companyName2 = `Around the Horn`;
const stmt = env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);
const batchResult = await env.DB.batch([
	stmt.bind(companyName1),
	stmt.bind(companyName2)
]);

company_name1 = "Bs Beverages"
company_name2 = "Around the Horn"
stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?")
batch_result = await self.env.DB.batch([
    stmt.bind(company_name1),
    stmt.bind(company_name2),
])

Parametry

statements: Array
- Pole D1PreparedStatements.

Návratové hodnoty

results: Array
- Pole D1Result objekty obsahující výsledky D1Database::prepare příkazy. Každý objekt se nachází na pozici v poli odpovídající pozici v poli původního D1Database::prepare příkaz uvnitř statements.
- Viz D1Result pro další informace o tomto objektu.

Příklad návratových hodnot

const companyName1 = `Bs Beverages`;
const companyName2 = `Around the Horn`;
const stmt = await env.DB.batch([
	env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`).bind(companyName1),
	env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`).bind(companyName2)
]);
return Response.json(stmt)

from workers import Response

company_name1 = "Bs Beverages"
company_name2 = "Around the Horn"
stmt = await self.env.DB.batch([
    self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(company_name1),
    self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(company_name2),
])
return Response.json(stmt)

[
  {
    "success": true,
    "meta": {
      "served_by": "miniflare.db",
      "duration": 0,
      "changes": 0,
      "last_row_id": 0,
      "changed_db": false,
      "size_after": 8192,
      "rows_read": 4,
      "rows_written": 0
    },
    "results": [
      {
        "CustomerId": 11,
        "CompanyName": "Bs Beverages",
        "ContactName": "Victoria Ashworth"
      },
      {
        "CustomerId": 13,
        "CompanyName": "Bs Beverages",
        "ContactName": "Random Name"
      }
    ]
  },
  {
    "success": true,
    "meta": {
      "served_by": "miniflare.db",
      "duration": 0,
      "changes": 0,
      "last_row_id": 0,
      "changed_db": false,
      "size_after": 8192,
      "rows_read": 4,
      "rows_written": 0
    },
    "results": [
      {
        "CustomerId": 4,
        "CompanyName": "Around the Horn",
        "ContactName": "Thomas Hardy"
      }
    ]
  }
]

console.log(stmt[1].results);

print(stmt[1].results.to_py())

[
  {
    "CustomerId": 4,
    "CompanyName": "Around the Horn",
    "ContactName": "Thomas Hardy"
  }
]

Pokyny

Dávky můžete sestavit opakovaným použitím stejného prepared statement:

const companyName1 = `Bs Beverages`;
const companyName2 = `Around the Horn`;
const stmt = env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);
const batchResult = await env.DB.batch([
	stmt.bind(companyName1),
	stmt.bind(companyName2)
]);
return Response.json(batchResult);

from workers import Response

company_name1 = "Bs Beverages"
company_name2 = "Around the Horn"
stmt = self.env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?")
batch_result = await self.env.DB.batch([
    stmt.bind(company_name1),
    stmt.bind(company_name2),
])
return Response.json(batch_result)

`exec()`

Provede jeden nebo více dotazů přímo, bez prepared statements nebo parameter bindings.

const returnValue = await env.DB.exec(`SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"`);

return_value = await self.env.DB.exec('SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"')

Parametry

query: String Povinné
- Příkaz SQL dotazu bez bindingu parametrů.

Návratové hodnoty

D1ExecResult: Object
- count vlastnost obsahuje počet provedených dotazů.
- duration vlastnost obsahuje dobu trvání operace v milisekundách.
  - Viz D1ExecResult s dalšími informacemi.

Příklad návratových hodnot

const returnValue = await env.DB.exec(`SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"`);
return Response.json(returnValue);

from workers import Response

return_value = await self.env.DB.exec('SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"')
return Response.json(return_value)

{
  "count": 1,
  "duration": 1
}

Pokyny

Dojde-li k chybě, vyvolá se výjimka s dotazem a chybovou zprávou, provádění se zastaví a další příkazy se již nespustí. Viz Chyby a zjistěte více.
Tato metoda může mít horší výkon (prepared statements lze v některých případech znovu použít) a co je důležitější, je méně bezpečná.
Tuto metodu používejte pouze pro údržbu a jednorázové úlohy (například migrační úlohy).
Vstupem může být jeden nebo více dotazů oddělených \n.

`dump`

Vyexportuje celou databázi D1 do souboru kompatibilního s SQLite uvnitř ArrayBufferu.

const dump = await db.dump();
return new Response(dump, {
	status: 200,
	headers: {
		"Content-Type": "application/octet-stream",
	},
});

from workers import Response

dump = await db.dump()
return Response(dump, status=200, headers={"Content-Type": "application/octet-stream"})

Parametry

Žádné.

Návratové hodnoty

Žádné.

`withSession()`

Zahájí D1 relaci, která zajišťuje sekvenční konzistenci mezi dotazy prováděnými na vrácené D1DatabaseSession objekt.

const session = env.DB.withSession("<parameter>");

session = self.env.DB.withSession("<parameter>")

Parametry

first-primary: StringVolitelné
- Směruje první dotaz v relaci (ať už čtecí, nebo zápisový) na primární instanci databáze. Tuto možnost použijte, pokud potřebujete zahájit relaci s nejaktuálnějšími daty z primární instance databáze.
- Následující dotazy v rámci Session mohou využívat repliky pro čtení.
- Následující dotazy v rámci Session mají sekvenční konzistenci.
first-unconstrained: StringVolitelné
- Směruje první dotaz v relaci (ať už čtecí, nebo zápisový) na libovolnou instanci databáze. Tuto možnost použijte, pokud nepotřebujete zahájit relaci s nejaktuálnějšími daty a chcete od samého začátku relace minimalizovat latenci dotazů.
- Následující dotazy v rámci Session mají sekvenční konzistenci.
- Toto je výchozí chování, pokud není zadán žádný parametr.
bookmark: StringVolitelné
- A bookmark z předchozí relace D1 Session. To umožňuje zahájit novou relaci alespoň od zadaného bookmark.
- Následující dotazy v rámci Session mají sekvenční konzistenci.

Návratové hodnoty

D1DatabaseSession: Object
- Objekt, který obsahuje metody prepare() a batch() podobně jako D1Database, spolu s dalším getBookmark metoda.

Pokyny

Pro použití replikace pro čtení musíte použít D1 Sessions API, jinak budou všechny dotazy nadále prováděny pouze primární databází.
Můžete vrátit poslední zaznamenaný bookmark pro danou relaci Session pomocí session.getBookmark().

`D1DatabaseSession` metody

`getBookmark`

Načte nejnovější bookmark z relace D1 Session.

const session = env.DB.withSession("first-primary");
const result = await session
	.prepare(`SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'`)
	.run()
const { bookmark } = session.getBookmark();
	return bookmark;

session = self.env.DB.withSession("first-primary")
result = await session.prepare(
    "SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'"
).run()

bookmark = session.getBookmark()

Parametry

Žádné

Návratové hodnoty

bookmark: String | null
- A bookmark která identifikuje nejnovější verzi databáze, kterou zaznamenal poslední dotaz spuštěný v rámci Session.
- Vrátí null pokud v rámci relace není proveden žádný dotaz.

`prepare()`

Tato metoda je ekvivalentní s D1Database::prepare.

`batch()`

Tato metoda je ekvivalentní s D1Database::batch.

D1 Database

Metody

prepare()

Parametry

Návratové hodnoty

Pokyny

batch()

Parametry

Návratové hodnoty

Pokyny

exec()

Parametry

Návratové hodnoty

Pokyny

dump

Parametry

Návratové hodnoty

withSession()

Parametry

Návratové hodnoty

Pokyny

D1DatabaseSession metody

getBookmark

Parametry

Návratové hodnoty

prepare()

batch()

`prepare()`

`batch()`

`exec()`

`dump`

`withSession()`

`D1DatabaseSession` metody

`getBookmark`

`prepare()`

`batch()`