[D1] Docs for automatic read-only retries in D1

src/content/changelog/d1/2025-09-11-d1-automatic-read-retries.mdx

@@ -0,0 +1,22 @@
+---
+title: D1 automatically retries read-only queries
+description: D1 now detects read-only queries and automatically attempts up to 2 retries to execute those queries in the event of failures with retryable errors.
+products:
+  - d1
+  - workers
+date: 2025-09-11
+---
+
+D1 now detects read-only queries and automatically attempts up to 2 retries to execute those queries in the event of failures with retryable errors. You can view the number of execution attempts in the returned [response metadata](/d1/worker-api/return-object/#d1result) property `total_attempts`.
+
+At the moment, only read-only queries are retried, that is, queries containing only the following SQLite keywords: `SELECT`, `EXPLAIN`, `WITH`. Queries containing any [SQLite keyword](https://sqlite.org/lang_keywords.html) that leads to database writes are not retried.
+
+The retry success ratio among read-only retryable errors varies from 5% all the way up to 95%, depending on the underlying error and its duration (like network errors or other internal errors).
+
+The retry success ratio among all retryable errors is lower, indicating that there are write-queries that could be retried. Therefore, we recommend D1 users to continue applying [retries in their own code](/d1/best-practices/retry-queries/) for queries that are not read-only but are idempotent according to the business logic of the application.
+
+[D1 automatically query retries success ratio]
+
+D1 ensures that any retry attempt does not cause database writes, making the automatic retries safe from side-effects, even if a query slips through the read-only detection. D1 achieves this by checking for modifications after every query execution, and if any write occurred due to a retry attempt, the query is rolled back.
+
+The read-only query detection heuristics are simple for now, and there is room for improvement to capture more cases of queries that can be retried, so this is just the beginning.

src/content/docs/d1/best-practices/retry-queries.mdx

@@ -0,0 +1,31 @@
+---
+title: Retry queries
+pcx_content_type: concept
+sidebar:
+  order: 3
+
+---
+
+import { GitHubCode } from "~/components";
+
+D1 automatically retries read-only queries up to 2 more times when it encounters a retryable error.
+
+But it can be useful to retry queries from your application when you encounter an [error](/d1/observability/debug-d1/#error-list).
+
+## Example of retrying queries
+
+Consider the following example, taken from the [D1 read replication starter template](https://github.com/cloudflare/templates/blob/main/d1-starter-sessions-api-template/src/index.ts#L108).
+
+```ts
+function shouldRetry(err: unknown, nextAttempt: number) {
+  const errMsg = String(err);
+  const isRetryableError =
+    errMsg.includes("Network connection lost") ||
+    errMsg.includes("storage caused object to be reset") ||
+    errMsg.includes("reset because its code was updated");
+  if (nextAttempt <= 5 && isRetryableError) {
+    return true;
+  }
+  return false;
+}
+```

src/content/docs/d1/observability/debug-d1.mdx

@@ -79,6 +79,16 @@ Before retrying any failed operation:
 
 </Example>
 
+## Automatic retries
+
+D1 detects read-only queries and automatically attempts up to 2 retries to execute those queries in the event of failures with retryable errors.
+
+D1 ensures that any retry attempt does not cause database writes, making the automatic retries safe from side-effects, even if a query slips through the read-only detection. D1 achieves this by checking for modifications after every query execution, and if any write occurred due to a retry attempt, the query is rolled back.
+
+:::note
+Only read-only queries (queries containing only the following SQLite keywords: `SELECT`, `EXPLAIN`, `WITH`) are retried. Queries containing any [SQLite keyword](https://sqlite.org/lang_keywords.html) that leads to database writes are not retried.
+:::
+
 ## View logs
 
 View a stream of live logs from your Worker by using [`wrangler tail`](/workers/observability/logs/real-time-logs#view-logs-using-wrangler-tail) or via the [Cloudflare dashboard](/workers/observability/logs/real-time-logs#view-logs-from-the-dashboard).

src/content/docs/d1/worker-api/return-object.mdx

@@ -37,6 +37,7 @@ The methods [`D1PreparedStatement::run`](/d1/worker-api/prepared-statements/#run
     size_after: number, // the size of the database after the query is successfully applied
     rows_read: number, // the number of rows read (scanned) by this query
     rows_written: number // the number of rows written by this query
+    total_attempts: number //the number of total attempts to execute read-only, retryable query
   }
   results: array | null, // [] if empty, or null if it does not apply
 }