[D1] Adding PRAGMA optimize for D1 (#19996)

* Adding PRAGMA optimize for D1.

* Adding PRAGMA optimize definition to partial.

* Including a line in the best practices section.

* Fixing wording, linking to SQLite documentation.

* Minor wording update.

* Fixing incorrect description of PRAGMA optimize.

* Specifying that ANALYZE may not always run.

* Wording edit

* Adding corresponding D1 changelog.

* Adding changelog entry for DO.

* Editing wording to make link more explicit.

* Introducing glossary term query planner, adding more details.

* Adding D1 glossary.

* Update src/content/release-notes/d1.yaml

Co-authored-by: Vy Ton <[email protected]>

* Changing release note wording, explicitly mentioning
we don't support PRAGMA optimize(-1).

---------

Co-authored-by: Vy Ton <[email protected]>

Author: Oxyjun

src/content/docs/d1/best-practices/use-indexes.mdx

@@ -6,6 +6,8 @@ sidebar:
 
 ---
 
+import { GlossaryTooltip } from "~/components";
+
 Indexes enable D1 to improve query performance over the indexed columns for common (popular) queries by reducing the amount of data (number of rows) the database has to scan when running a query.
 
 ## When is an index useful?
@@ -62,6 +64,14 @@ SELECT * FROM orders WHERE order_date = '2023-05-01'
 
 In more complex cases, you can confirm whether an index was used by D1 by [analyzing a query](#test-an-index) directly.
 
+### Run `PRAGMA optimize`
+
+After creating an index, run the `PRAGMA optimize` command to improve your database performance.
+
+`PRAGMA optimize` runs `ANALYZE` command on each table in the database, which collects statistics on the tables and indices. These statistics allows the <GlossaryTooltip term="query planner">query planner</GlossaryTooltip> to generate the most efficient query plan when executing the user query.
+
+For more information, refer to [`PRAGMA optimize`](/d1/sql-api/sql-statements/#pragma-optimize).
+
 ## List indexes
 
 List the indexes on a database, as well as the SQL definition, by querying the `sqlite_schema` system table:

src/content/docs/d1/reference/glossary.mdx

@@ -0,0 +1,13 @@
+---
+title: Glossary
+pcx_content_type: glossary
+sidebar:
+  order: 12
+
+---
+
+import { Glossary } from "~/components"
+
+Review the definitions for terms used across Cloudflare's D1 documentation.
+
+<Glossary product="d1" />

src/content/glossary/d1.yaml

@@ -0,0 +1,6 @@
+---
+productName: D1
+entries:
+  - term: "query planner"
+    general_definition: |-
+      A component in a database management system which takes a user query and generates the most efficient plan of executing that query (the query plan). For example, the query planner decides which indices to use, or which table to access first.

src/content/partials/d1/use-pragma-statements.mdx

@@ -2,7 +2,7 @@
 {}
 ---
 
-import { Details } from "~/components";
+import { Details, GlossaryTooltip } from "~/components";
 
 The PRAGMA statement examples on this page use the following SQL.
 
@@ -411,3 +411,19 @@ PRAGMA defer_foreign_keys = off
 ```
 
 Refer to the [foreign key documentation](/d1/sql-api/foreign-keys/) to learn more about how to work with foreign keys.
+
+### `PRAGMA optimize`
+
+Attempts to optimize all schemas in a database by running the `ANALYZE` command for each table, if necessary. `ANALYZE` updates an internal table which contain statistics about tables and indices. These statistics helps the <GlossaryTooltip term="query planner">query planner</GlossaryTooltip> to execute the input query more efficiently.
+
+When `PRAGMA optimize` runs `ANALYZE`, it sets a limit to ensure the command does not take too long to execute. Alternatively, `PRAGMA optimize` may deem it unnecessary to run `ANALYZE` (for example, if the schema has not changed significantly). In this scenario, no optimizations are made.
+
+We recommend running this command after making any changes to the schema (for example, after [creating an index](/d1/best-practices/use-indexes/)).
+
+:::note
+Currently, D1 does not support `PRAGMA optimize(-1)`.
+
+`PRAGMA optimize(-1)` is a command which displays all optimizations that would have been performed without actually executing them.
+:::
+
+Refer to [SQLite PRAGMA optimize documentation](https://www.sqlite.org/pragma.html#pragma_optimize) for more information on how `PRAGMA optimize` optimizes a database.

src/content/release-notes/d1.yaml

@@ -5,11 +5,16 @@ productLink: "/d1/"
 productArea: Developer platform
 productAreaLink: /workers/platform/changelog/platform/
 entries:
+  - publish_date: "2025-02-19"
+    title: D1 supports `PRAGMA optimize`
+    description: |-
+      D1 now supports `PRAGMA optimize` command, which can improve database query performance. It is recommended to run this command after a schema change (for example, after creating an index). Refer to [`PRAGMA optimize`](/d1/sql-api/sql-statements/#pragma-optimize) for more information.
+
   - publish_date: "2025-02-04"
     title: Fixed bug with D1 read-only access via UI and /query REST API.
     description: |-
       Fixed a bug with D1 permissions which allowed users with read-only roles via the UI and users with read-only API tokens via the `/query` [REST API](/api/resources/d1/subresources/database/methods/query/) to execute queries that modified databases. UI actions via the `Tables` tab, such as creating and deleting tables, were incorrectly allowed with read-only access. However, UI actions via the `Console` tab were not affected by this bug and correctly required write access.
-      
+
       Write queries with read-only access will now fail. If you relied on the previous incorrect behavior, please assign the correct roles to users or permissions to API tokens to perform D1 write queries.
 
   - publish_date: "2025-01-13"

src/content/release-notes/durable-objects.yaml

@@ -5,13 +5,19 @@ productLink: "/durable-objects/"
 productArea: Developer platform
 productAreaLink: /workers/platform/changelog/platform/
 entries:
+  - publish_date: "2025-02-19"
+    description: |-
+      SQLite-backed Durable Objects now support `PRAGMA optimize` command, which can improve database query performance. It is recommended to run this command after a schema change (for example, after creating an index). Refer to [`PRAGMA optimize`](/d1/sql-api/sql-statements/#pragma-optimize) for more information.
+
   - publish_date: "2025-02-11"
     description: |-
       When Durable Objects generate an "internal error" exception in response to certain failures, the exception message may provide a reference ID that customers can include in support communication for easier error identification. For example, an exception with the new message might look like: `internal error; reference = 0123456789abcdefghijklmn`.
+
   - publish_date: "2024-10-07"
     title: Alarms re-enabled in (beta) SQLite-backed Durable Object classes
     description: |-
       The issue identified with [alarms](/durable-objects/api/alarms/) in [beta Durable Object classes with a SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend) has been resolved and alarms have been re-enabled.
+
   - publish_date: "2024-09-27"
     title: Alarms disabled in (beta) SQLite-backed Durable Object classes
     description: |-