[D1] Creating proper API documentation (#17923)

Oxyjun · lambrospetrou · marciocloudflare · web-flow · commit e2f26ba12aa4 · 2024-11-19T17:16:49.000Z
* Adding placeholder for new API section.

* Initializing await stmt API chapter.

* Reordering the sidebar. Adding intro to stmt.methods.

* Setting up Worker Bindings API chapters.

* Settling on naming convention, fleshing out .db chapter.

* Setting up the database API section.

* Fleshing out API chapters.

* Updating D1 API docs.

* Adding in more information to be complete.

* Apply suggestions from code review

Co-authored-by: Lambros Petrou &lt;lambrospetrou@gmail.com&gt;

* Update src/content/docs/d1/worker-api/query.mdx

* Updating the Return Object chapter. Testing more APIs.

* Fleshing out the API docs in more detail.

* Fixing broken link.

* Changing reference to mention Worker Binding APIs.

* Small rename.

* Small rename.

* Updating the chapters

* Modifying the structure to align with discussion.

* Renaming extensions header for better clarity.

* Adding changelog entry for including multiple queries in a single prepared statement.

* Updating wording in Get started to match new folders.

* Fixing broken link

* Implementing feedback.

* Removing references to multi-statement prepare().

* Fixing broken links

* Grammar fixes and deleting redundant comment block.

* Apply suggestions from code review

Co-authored-by: marciocloudflare &lt;83226960+marciocloudflare@users.noreply.github.com&gt;

* Minor rename of the chapter

* Cleaning up the structure by method hierarchy.

* Adding a note for those who are following the tutorial with an existing Worker.

* Actioning PR feedback.

* Turning all method names into links to the relevant header.

---------

Co-authored-by: Lambros Petrou &lt;lambrospetrou@gmail.com&gt;
Co-authored-by: marciocloudflare &lt;83226960+marciocloudflare@users.noreply.github.com&gt;
diff --git a/public/_redirects b/public/_redirects
@@ -295,6 +295,7 @@
 /d1/configuration/remote-development/ /d1/build-with-d1/remote-development/ 301
 /d1/build-with-d1/import-data/ /d1/build-with-d1/import-export-data/ 301
 /d1/reference/database-commands/ /d1/reference/sql-statements/ 301
+/d1/reference/sql-statements/ /d1/sql-api/sql-statements/ 301
 
 # data loss prevention (dlp)
 /cloudflare-one/policies/data-loss-prevention/integration-profiles/ /cloudflare-one/policies/data-loss-prevention/dlp-profiles/integration-profiles/ 301
diff --git a/src/content/docs/d1/build-with-d1/d1-client-api.mdx b/src/content/docs/d1/build-with-d1/d1-client-api.mdx
@@ -449,7 +449,7 @@ D1 PRAGMA statements only apply to the current transaction.
 
 :::
 
-For the full list of PRAGMA statements supported by D1, see [SQL statements](/d1/reference/sql-statements).
+For the full list of PRAGMA statements supported by D1, see [SQL statements](/d1/sql-api/sql-statements).
 
 ## Errors
 
diff --git a/src/content/docs/d1/configuration/index.mdx b/src/content/docs/d1/configuration/index.mdx
@@ -2,7 +2,7 @@
 title: Configuration
 pcx_content_type: navigation
 sidebar:
-  order: 4
+  order: 6
   group:
     hideIndex: true
 ---
diff --git a/src/content/docs/d1/d1-api.mdx b/src/content/docs/d1/d1-api.mdx
@@ -3,6 +3,6 @@ pcx_content_type: navigation
 title: D1 REST API
 external_link: /api/operations/cloudflare-d1-create-database
 sidebar:
-  order: 10
+  order: 5
 
 ---
diff --git a/src/content/docs/d1/demos.mdx b/src/content/docs/d1/demos.mdx
@@ -2,7 +2,7 @@
 pcx_content_type: navigation
 title: Demos and architectures
 sidebar:
-  order: 8
+  order: 10
 
 ---
 
diff --git a/src/content/docs/d1/examples/index.mdx b/src/content/docs/d1/examples/index.mdx
@@ -4,7 +4,7 @@ hideChildren: false
 pcx_content_type: navigation
 title: Examples
 sidebar:
-  order: 6
+  order: 8
   group:
     hideIndex: true
 ---
diff --git a/src/content/docs/d1/get-started.mdx b/src/content/docs/d1/get-started.mdx
@@ -24,6 +24,10 @@ This guide instructs you through:
 
 You can perform these tasks through the CLI or through the Cloudflare dashboard.
 
+:::note
+If you already have an existing Worker and an existing D1 database, follow this tutorial from [3. Bind your Worker to your D1 database](/d1/get-started/#3-bind-your-worker-to-your-d1-database).
+:::
+
 ## Prerequisites
 
 <Render file="prereqs" product="workers" />
@@ -531,5 +535,5 @@ In this tutorial, you have:
 If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the [Cloudflare Developers community on Discord](https://discord.cloudflare.com).
 
 - See supported [Wrangler commands for D1](/workers/wrangler/commands/#d1).
-- Learn how to use the [D1 client API](/d1/build-with-d1/d1-client-api/) within your Worker.
+- Learn how to use [D1 Worker Binding APIs](/d1/worker-api/) within your Worker, and test them from the [API playground](/d1/worker-api/#api-playground).
 - Explore [community projects built on D1](/d1/reference/community-projects/).
diff --git a/src/content/docs/d1/observability/index.mdx b/src/content/docs/d1/observability/index.mdx
@@ -2,7 +2,7 @@
 title: Observability
 pcx_content_type: navigation
 sidebar:
-  order: 5
+  order: 7
   group:
     hideIndex: true
 ---
diff --git a/src/content/docs/d1/platform/index.mdx b/src/content/docs/d1/platform/index.mdx
@@ -2,7 +2,7 @@
 pcx_content_type: navigation
 title: Platform
 sidebar:
-  order: 8
+  order: 10
   group:
     hideIndex: true
 ---
diff --git a/src/content/docs/d1/reference/index.mdx b/src/content/docs/d1/reference/index.mdx
@@ -2,7 +2,7 @@
 pcx_content_type: navigation
 title: Reference
 sidebar:
-  order: 9
+  order: 11
   group:
     hideIndex: true
 ---
diff --git a/src/content/docs/d1/sql-api/index.mdx b/src/content/docs/d1/sql-api/index.mdx
@@ -0,0 +1,12 @@
+---
+title: SQL API
+pcx_content_type: navigation
+sidebar:
+  order: 5
+  group:
+    hideIndex: true
+---
+
+import { DirectoryListing } from "~/components";
+
+<DirectoryListing />
diff --git a/src/content/docs/d1/sql-api/sql-statements.mdx b/src/content/docs/d1/sql-api/sql-statements.mdx
@@ -2,22 +2,33 @@
 title: SQL statements
 pcx_content_type: concept
 sidebar:
-  order: 6
+  order: 1
 ---
 
 import { Details, Render } from "~/components";
 
-D1 supports a number of database-level commands that allow you to list tables, indexes, and inspect the schema for a given table or index.
+D1 is compatible with most SQLite's SQL convention since it leverages SQLite's query engine. D1 supports a number of database-level statements that allow you to list tables, indexes, and inspect the schema for a given table or index.
 
-## Database statements
+You can execute any of these statements via the D1 console in the Cloudflare dashboard, [`wrangler d1 execute`](/workers/wrangler/commands/#d1), or with the [D1 Worker Bindings API](/d1/worker-api/d1-database).
 
-D1 supports a number of database-level statements that allow you to list tables, indexes, and inspect the schema for a given table or index.
+## Supported SQLite extensions
 
-You can execute any of these statements via the D1 console in the Cloudflare dashboard, [`wrangler d1 execute`](/workers/wrangler/commands/#d1), or with the [D1 client API](/d1/build-with-d1/d1-client-api/).
+D1 supports a subset of SQLite extensions for added functionality, including:
+
+- Default SQLite extensions.
+- [FTS5 module](https://www.sqlite.org/fts5.html) for full-text search.
+
+## Compatible PRAGMA statements
+
+D1 supports some [SQLite PRAGMA](https://www.sqlite.org/pragma.html) statements. The PRAGMA statement is an SQL extension for SQLite. PRAGMA commands can be used to:
+
+- Modify the behavior of certain SQLite operations.
+- Query the SQLite library for internal data about schemas or tables (but note that PRAGMA statements cannot query the contents of a table).
+- Control environmental variables.
 
 <Render file="use-pragma-statements" />
 
-### Query `sqlite_master`
+## Query `sqlite_master`
 
 You can also query the `sqlite_master` table to show all tables, indexes, and the original SQL used to generate them:
 
@@ -44,11 +55,21 @@ SELECT name, sql FROM sqlite_master
       }
 ```
 
-## SQLite Extensions
+## Search with LIKE
 
-D1 supports a subset of SQLite extensions for added functionality, including:
+You can perform a search using SQL's `LIKE` operator:
 
-- [FTS5 module](https://www.sqlite.org/fts5.html) for full-text search
+```js
+const { results } = await env.DB.prepare(
+	"SELECT * FROM Customers WHERE CompanyName LIKE ?",
+)
+	.bind("%eve%")
+	.all();
+console.log("results: ", results);
+```
+```js output
+results:  [...]
+```
 
 ## Related resources
 
diff --git a/src/content/docs/d1/tutorials/index.mdx b/src/content/docs/d1/tutorials/index.mdx
@@ -4,7 +4,7 @@ pcx_content_type: navigation
 title: Tutorials
 hideChildren: true
 sidebar:
-  order: 7
+  order: 9
 
 ---
 
diff --git a/src/content/docs/d1/worker-api/d1-database.mdx b/src/content/docs/d1/worker-api/d1-database.mdx
diff --git a/src/content/docs/d1/worker-api/index.mdx b/src/content/docs/d1/worker-api/index.mdx
diff --git a/src/content/docs/d1/worker-api/prepared-statements.mdx b/src/content/docs/d1/worker-api/prepared-statements.mdx
diff --git a/src/content/docs/d1/worker-api/return-object.mdx b/src/content/docs/d1/worker-api/return-object.mdx
diff --git a/src/content/partials/d1/use-pragma-statements.mdx b/src/content/partials/d1/use-pragma-statements.mdx
