D1 Database

Worker から D1 データベースを操作するには、Worker に渡される環境バインディング（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

D1 バインディングの型は D1Database で、次のメソッドをサポートします。

メソッド

`prepare()`

後で実行するクエリステートメントを準備します。

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)

パラメーター

query: String 必須
- データベースで実行する SQL クエリです。

戻り値

D1PreparedStatement: Object
- メソッドだけを持つオブジェクトです。準備済みステートメントのメソッドを参照してください。

使い方

次のように、bind メソッドで値をクエリステートメントに動的にバインドできます。

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")

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)

詳細は bind メソッドのドキュメントを参照してください。

`batch()`

複数の SQL ステートメントを 1 回の呼び出しでデータベースに送ります。D1 へのネットワーク往復が減るため、パフォーマンスが大きく向上することがあります。D1 はオートコミットで動作します。この実装では、リスト内の各ステートメントが順次、非並行で実行およびコミットされることを保証します。

バッチしたステートメントは SQL トランザクション ↗ です。シーケンス内のステートメントが失敗すると、そのステートメントに対するエラーが返り、シーケンス全体が中止またはロールバックされます。

バッチステートメントを送るには、D1Database::batch に準備済みステートメントのリストを渡し、同じ順序で結果を受け取ります。

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),
])

パラメーター

statements: Array
- D1PreparedStatement の配列です。

戻り値

results: Array
- D1Database::prepare ステートメントの結果を含む D1Result オブジェクトの配列です。各オブジェクトの配列位置は、statements 内の元の D1Database::prepare ステートメントの位置に対応します。
- このオブジェクトの詳細は D1Result を参照してください。

戻り値の例

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"
  }
]

使い方

同じ準備済みステートメントを再利用してバッチを組み立てられます。

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()`

準備済みステートメントやパラメーターバインディングなしで、1 つ以上のクエリを直接実行します。

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"')

パラメーター

query: String 必須
- パラメーターバインディングのない SQL クエリステートメントです。

戻り値

D1ExecResult: Object
- count プロパティは、実行したクエリの数です。
- duration プロパティは、操作の所要時間（ミリ秒）です。
  - 詳細は D1ExecResult を参照してください。

戻り値の例

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
}

使い方

エラーが起きると、クエリとエラーメッセージ付きの例外がスローされ、実行は止まり、以降のステートメントは実行されません。詳細はエラーを参照してください。
このメソッドはパフォーマンスが劣ることがあり（準備済みステートメントは再利用できる場合があります）、より重要な点として、安全性が低くなります。
メンテナンスや一度きりの作業（マイグレーションジョブなど）にだけ使います。
入力は、\n で区切った 1 つまたは複数のクエリにできます。

`dump`

D1 データベース全体を、ArrayBuffer 内の SQLite 互換ファイルとしてダンプします。

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"})

パラメーター

なし。

戻り値

なし。

`withSession()`

返される D1DatabaseSession オブジェクト上で実行するクエリの間で、逐次一貫性を保つ D1 セッションを開始します。

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

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

パラメーター

first-primary: String任意
- セッションの最初のクエリ（読み取りまたは書き込み）を、プライマリデータベースインスタンスへ送ります。プライマリの最新データでセッションを始めたい場合に使います。
- セッション内の以降のクエリは、リードレプリカを使うことがあります。
- セッション内の以降のクエリは逐次一貫性を持ちます。
first-unconstrained: String任意
- セッションの最初のクエリ（読み取りまたは書き込み）を、任意のデータベースインスタンスへ送ります。最新データで始める必要がなく、セッション開始直後からクエリ遅延を最小化したい場合に使います。
- セッション内の以降のクエリは逐次一貫性を持ちます。
- パラメーターを指定しない場合のデフォルトの動作です。
bookmark: String任意
- 以前の D1 セッションの bookmark です。指定した bookmark 以降の状態から新しいセッションを始められます。
- セッション内の以降のクエリは逐次一貫性を持ちます。

戻り値

D1DatabaseSession: Object
- prepare() と batch() を D1Database と同様に持つオブジェクトです。加えて getBookmark メソッドがあります。

使い方

リードレプリケーションを使うには D1 Sessions API が必要です。使わない場合、すべてのクエリはプライマリデータベースだけで実行され続けます。
指定したセッションで最後に遭遇した bookmark は session.getBookmark() で取得できます。

`D1DatabaseSession` のメソッド

`getBookmark`

D1 セッションから最新の bookmark を取得します。

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

パラメーター

なし

戻り値

bookmark: String | null
- セッション内で最後に実行したクエリが見た、データベースの最新バージョンを識別する bookmark です。
- セッション内でクエリを実行していない場合は null を返します。

`prepare()`

このメソッドは D1Database::prepare と同等です。

`batch()`

このメソッドは D1Database::batch と同等です。

D1 Database

メソッド

prepare()

パラメーター

戻り値

使い方

batch()

パラメーター

戻り値

使い方

exec()

パラメーター

戻り値

使い方

dump

パラメーター

戻り値

withSession()

パラメーター

戻り値

使い方

D1DatabaseSession のメソッド

getBookmark

パラメーター

戻り値

prepare()

batch()

`prepare()`

`batch()`

`exec()`

`dump`

`withSession()`

`D1DatabaseSession` のメソッド

`getBookmark`

`prepare()`

`batch()`