D1 のデバッグ

D1 では、データベースのクエリ時に返る例外を捕捉し、エラーを記録できます。D1 のデバッグには、Workers のデバッグ と同じツールを使います。

D1 の stmt. および db. メソッドは、エラー発生時に Error オブジェクト ↗ をスローします。例外を捕捉するには、e.message の値を記録します。

たとえば、次のコードは無効なキーワードを含むクエリです。INSERT ではなく INSERTZ になっています。

try {
    // This is an intentional misspelling
    await db.exec("INSERTZ INTO my_table (name, employees) VALUES ()");
} catch (e: any) {
    console.error({
        message: e.message
    });
}

上記のコードは、次のエラーメッセージをスローします。

{
	"message": "D1_EXEC_ERROR: Error in line 1: INSERTZ INTO my_table (name, employees) VALUES (): sql error: near \"INSERTZ\": syntax error in INSERTZ INTO my_table (name, employees) VALUES () at offset 0"
}

D1 は、詳細なエラーメッセージに加えて、次のエラー定数を返します。

次の表は、D1_ERROR の具体例です。

D1 は読み取り専用クエリを検出し、再試行可能なエラーで失敗した場合、それらのクエリの実行を最大 2 回まで自動的に再試行します。

D1 は、再試行がデータベースへの書き込みを起こさないことを保証します。読み取り専用の検出をすり抜けて変更を伴うクエリがあっても、自動再試行は副作用から安全です。D1 は各クエリ実行後に変更の有無を確認し、再試行によって書き込みが起きていた場合はクエリをロールバックします。

Worker のライブログのストリームは、wrangler tail または Cloudflare ダッシュボード で確認できます。

• バグの報告や機能のリクエストは、Cloudflare Community Forums ↗ へ進みます。
• フィードバックは D1 の Discord チャンネル ↗ へ進みます。
• Wrangler で問題がある場合は、Wrangler の GitHub リポジトリ ↗ で報告します。

バグ報告には、次のうちできるだけ多くを含めてください。

• データベースの ID。データベース名と ID の対応は wrangler d1 list で確認します。
• 問題が起きたときに実行したクエリ。個人を特定できる情報（PII）は必ず伏せます。
• クエリを行う Worker のコード。Workers Binding API を使った bind() の呼び出しも含みます。
• error.cause.message の内容を含む、エラーテキスト全文。

• Workers のデバッグ方法 を学ぶ。
• Worker と D1 が生成する ログへのアクセス方法 を理解する。
• wrangler dev で Worker と D1 をローカル実行し、デプロイ前に問題をデバッグ する。