[D1] Creating proper API documentation

public/_redirects

@@ -294,6 +294,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

src/content/changelogs/d1.yaml

@@ -5,6 +5,12 @@ productLink: "/d1/"
 productArea: Developer platform
 productAreaLink: /workers/platform/changelog/platform/
 entries:
+  - publish_date: "2024-11-18"
+    title: Support for multiple queries in a single prepared statement
+    description: |-
+      You can now have multiple queries in a single prepared statement when using `db.prepare`. To use this feature, separate each query with a semi-colon. Prepared statements with multiple queries only returns the results of the last query, even though all queries are executed. Additionally, you can only bind parameters to the last query in the prepared statement.
+
+      For more information, refer to [`db.prepare` guidance](/d1/worker-api/prepare-a-statement/#guidance).
   - publish_date: "2024-08-23"
     title: D1 alpha databases have stopped accepting SQL queries
     description: |-

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
 

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

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

src/content/docs/d1/demos.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: navigation
 title: Demos and architectures
 sidebar:
-  order: 8
+  order: 10
 
 ---
 

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

src/content/docs/d1/get-started.mdx

@@ -532,5 +532,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 the [D1 Worker Binding API](/d1/worker-api/) within your Worker.
 - Explore [community projects built on D1](/d1/reference/community-projects/).

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

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

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

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 />

src/content/docs/d1/reference/sql-statements.mdx → 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/prepare-a-statement).
 
-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
 

src/content/docs/d1/tutorials/index.mdx

@@ -4,7 +4,7 @@ pcx_content_type: navigation
 title: Tutorials
 hideChildren: true
 sidebar:
-  order: 7
+  order: 9
 
 ---
 

src/content/docs/d1/worker-api/index.mdx

@@ -0,0 +1,128 @@
+---
+pcx_content_type: navigation
+title: D1 Worker Binding API
+sidebar:
+  order: 4
+---
+
+import { DirectoryListing, Details, Steps } from "~/components";
+
+You can execute queries on your D1 database through SQL query statements. To do this, you need to perform the following steps:
+
+1. [Prepare a statement](/d1/worker-api/prepare-a-statement).
+2. [Run the prepared statement](/d1/worker-api/run-a-statement).
+3. Analyze the [return object](/d1/worker-api/return-object) (if necessary).
+
+Refer to the relevant sections for the API documentation.
+
+## Typescript support
+
+D1 Worker Bindings API is fully-typed via the `@cloudflare/workers-types` package, and also supports [generic types](https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-types) as part of its TypeScript API. A generic type allows you to provide an optional _type parameter_ so that a function understands the type of the data it is handling.
+
+When using the [query statement methods](#query-statement-methods) `stmt.run()`, `stmt.raw()` and `stmt.first()`, you can provide a type representing each database row. D1's API will [return the result object](#return-object) with the correct type.
+
+For example, providing an `OrderRow` type as a type parameter to `stmt.run()` will return a typed `Array<OrderRow>` object instead of the default `Record<string, unknown>` type:
+
+```ts
+// Row definition
+type OrderRow = {
+Id: string;
+CustomerName: string;
+OrderDate: number;
+};
+
+// Elsewhere in your application
+const result = await env.MY_DB.prepare(
+"SELECT Id, CustomerName, OrderDate FROM [Order] ORDER BY ShippedDate DESC LIMIT 100",
+).run<OrderRow>();
+```
+
+## API playground
+
+The D1 Worker Binding API playground is an `index.js` file where you can test each of the documented Worker Binding APIs for D1. The file builds from the end-state of the [Get started](/d1/get-started/#write-queries-within-your-worker) code.
+
+You can use this alongside the API documentation to better understand how each API works.
+
+Follow the steps to setup your API playground.
+
+### 1. Complete the Get started tutorial
+
+Complete the [Get started](/d1/get-started/#write-queries-within-your-worker) tutorial. Ensure you use JavaScript instead of TypeScript.
+
+### 2. Modify the content of `index.js`
+
+Replace the contents of your `index.js` file with the below to view the effect of each API.
+
+<Details header="index.js" open={false}>
+```js
+export default {
+  async fetch(request, env) {
+    const { pathname } = new URL(request.url);
+
+    const companyName1 = `Bs Beverages`;
+    const companyName2 = `Around the Horn`;
+    const stmt = env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);
+
+    if (pathname === `/RUN`){
+    const returnValue = await stmt.bind(companyName1).run()
+    return Response.json(returnValue);
+
+  } else if (pathname === `/RAW`){
+    const returnValue = await stmt.bind(companyName1).raw();
+    return Response.json(returnValue);
+
+  } else if (pathname === `/FIRST`){
+    const returnValue = await stmt.bind(companyName1).first();
+    return Response.json(returnValue);
+
+  } else if (pathname === `/BATCH`) {
+    const batchResult = await env.DB.batch([
+      stmt.bind(companyName1),
+      stmt.bind(companyName2)
+    ]);
+    // const returnValue = await stmt.run();
+    return Response.json(batchResult);
+  }
+
+    return new Response(
+    `Welcome to the D1 API Playground!
+		\nChange the URL to test the methods inside your index.js file.`,
+    );
+  },
+  };
+
+```
+</Details>
+
+### 3. Deploy the Worker
+
+<Steps>
+1. Navigate to your tutorial directory you created by following step 1.
+2. Run `npx wrangler dev`.
+	```sh
+	npx wrangler dev
+	```
+	```sh output
+	 ⛅️ wrangler 3.85.0 (update available 3.86.1)
+	-------------------------------------------------------
+
+	Your worker has access to the following bindings:
+	- D1 Databases:
+		- DB: <DATABASE_NAME> (DATABASE_ID) (local)
+	⎔ Starting local server...
+	[wrangler:inf] Ready on http://localhost:8787
+	╭───────────────────────────╮
+	│  [b] open a browser       │
+	│  [d] open devtools        │
+	│  [l] turn off local mode  │
+	│  [c] clear console        │
+	│  [x] to exit              │
+	╰───────────────────────────╯
+	```
+3. Open a browser at the specified address.
+</Steps>
+
+### 4. Test the APIs
+
+Change the URL to test the various D1 Worker Binding APIs.
+