[Hyperdrive] add drivers and orms docs (#22125)

* [Hyperdrive] drafting custom cert support for Hyperdrive

* corrections

* wip

* add changelog

* adjust per comments

* add note on wrangler version

* add troubleshooting guides for ssl certs

* change changelog entry date

* Update src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx

* Update src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx

* PCX review

* add drivers and orms to hyperdrive docs

* Apply suggestions from code review

* Apply suggestions from code review

* Specifying product when rendering partials

* Importing Render components

* Fixing invalid links

* adjust per discord feedback

* more nits

* Pushing changes to Postgres Drizzle ORM tutorial

* Editing MySQL version of the tutorial

* Adding note about when to run the optional
migration step.

* Removing outdated redirects to avoid breaking

* Adding missing redirects.

---------

Co-authored-by: Jun Lee <[email protected]>

Author: 2 people

public/__redirects

@@ -1712,26 +1712,45 @@
 /hyperdrive/learning/how-hyperdrive-works/ /hyperdrive/configuration/how-hyperdrive-works/ 301
 /hyperdrive/learning/connect-to-postgres/ /hyperdrive/examples/connect-to-postgres/ 301
 /hyperdrive/learning/query-caching/ /hyperdrive/configuration/query-caching/ 301
-/hyperdrive/learning/troubleshooting/ /hyperdrive/reference/troubleshooting/ 301
+/hyperdrive/learning/troubleshooting/ /hyperdrive/observability/troubleshooting/ 301
 /hyperdrive/changelog/ /hyperdrive/platform/release-notes/ 301
 /hyperdrive/platform/changelog/ /hyperdrive/platform/release-notes/ 301
 /hyperdrive/learning/ /hyperdrive/configuration/ 301
 /hyperdrive/reference/metrics/ /hyperdrive/observability/metrics/ 301
 /hyperdrive/reference/troubleshooting/ /hyperdrive/observability/troubleshooting/ 301
-/hyperdrive/examples/aws-rds-aurora/ /hyperdrive/examples/connect-to-postgres/aws-rds-aurora/ 301
-/hyperdrive/examples/azure/ /hyperdrive/examples/connect-to-postgres/azure/ 301
-/hyperdrive/examples/cockroachdb/ /hyperdrive/examples/connect-to-postgres/cockroachdb/ 301
-/hyperdrive/examples/digital-ocean/ /hyperdrive/examples/connect-to-postgres/digital-ocean/ 301
-/hyperdrive/examples/google-cloud-sql/ /hyperdrive/examples/connect-to-postgres/google-cloud-sql/ 301
-/hyperdrive/examples/materialize/ /hyperdrive/examples/connect-to-postgres/materialize/ 301
-/hyperdrive/examples/neon/ /hyperdrive/examples/connect-to-postgres/neon/ 301
-/hyperdrive/examples/nile/ /hyperdrive/examples/connect-to-postgres/nile/ 301
-/hyperdrive/examples/pgedge/ /hyperdrive/examples/connect-to-postgres/pgedge/ 301
-/hyperdrive/examples/supabase/ /hyperdrive/examples/connect-to-postgres/supabase/ 301
-/hyperdrive/examples/timescale/ /hyperdrive/examples/connect-to-postgres/timescale/ 301
-/hyperdrive/examples/xata/ /hyperdrive/examples/connect-to-postgres/xata/ 301
-/hyperdrive/examples/fly/ /hyperdrive/examples/connect-to-postgres/fly/ 301
 
+/hyperdrive/examples/aws-rds-aurora/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora/ 301
+/hyperdrive/examples/azure/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/azure/ 301
+/hyperdrive/examples/cockroachdb/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb/ 301
+/hyperdrive/examples/digital-ocean/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/digital-ocean/ 301
+/hyperdrive/examples/google-cloud-sql/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/google-cloud-sql/ 301
+/hyperdrive/examples/materialize/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize/ 301
+/hyperdrive/examples/neon/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon/ 301
+/hyperdrive/examples/nile/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/nile/ 301
+/hyperdrive/examples/pgedge/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/pgedge/ 301
+/hyperdrive/examples/supabase/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/ 301
+/hyperdrive/examples/timescale/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale/ 301
+/hyperdrive/examples/xata/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata/ 301
+/hyperdrive/examples/fly/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly/ 301
+
+/hyperdrive/examples/connect-to-postgres/aws-rds-aurora/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora/ 301
+/hyperdrive/examples/connect-to-postgres/azure/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/azure/ 301
+/hyperdrive/examples/connect-to-postgres/cockroachdb/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb/ 301
+/hyperdrive/examples/connect-to-postgres/digital-ocean/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/digital-ocean/ 301
+/hyperdrive/examples/connect-to-postgres/fly/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly/ 301
+/hyperdrive/examples/connect-to-postgres/google-cloud-sql/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/google-cloud-sql/ 301
+/hyperdrive/examples/connect-to-postgres/materialize/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize/ 301
+/hyperdrive/examples/connect-to-postgres/neon/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon/ 301
+/hyperdrive/examples/connect-to-postgres/nile/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/nile/ 301
+/hyperdrive/examples/connect-to-postgres/pgedge/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/pgedge/ 301
+/hyperdrive/examples/connect-to-postgres/supabase/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/ 301
+/hyperdrive/examples/connect-to-postgres/timescale/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale/ 301
+/hyperdrive/examples/connect-to-postgres/xata/ /hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata/ 301
+
+/hyperdrive/examples/connect-to-mysql/planetscale/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale/ 301
+/hyperdrive/examples/connect-to-mysql/azure/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/azure/ 301
+/hyperdrive/examples/connect-to-mysql/google-cloud-sql/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/google-cloud-sql/ 301
+/hyperdrive/examples/connect-to-mysql/aws-rds-aurora/ /hyperdrive/examples/connect-to-mysql/mysql-database-providers/aws-rds-aurora/ 301
 
 /hyperdrive/reference/supported-databases/ /hyperdrive/reference/supported-databases-and-features/ 301
 /hyperdrive/configuration/connect-to-postgres/ /hyperdrive/examples/connect-to-postgres/ 301

src/content/docs/hyperdrive/configuration/connect-to-private-database.mdx

@@ -199,7 +199,7 @@ Validate that you can connect to your database from Workers and make queries.
 
 Use Postgres.js to send a test query to validate that the connection has been successful.
 
-<Render file="use-postgresjs-to-make-query" product="hyperdrive" />
+<Render file="use-postgres-js-to-make-query" product="hyperdrive" />
 
 Now, deploy your Worker:
 

src/content/docs/hyperdrive/examples/connect-to-mysql/index.mdx

@@ -32,19 +32,7 @@ npx wrangler hyperdrive create my-first-hyperdrive --connection-string="mysql://
 
 The command above will output the ID of your Hyperdrive, which you will need to set in the [Wrangler configuration file](/workers/wrangler/configuration/) for your Workers project:
 
-<WranglerConfig>
-
-```toml
-# required for database drivers to function
-compatibility_flags = ["nodejs_compat"]
-compatibility_date = "2024-09-23"
-
-[[hyperdrive]]
-binding = "HYPERDRIVE"
-id = "<your-hyperdrive-id-here>"
-```
-
-</WranglerConfig>
+<Render file="hyperdrive-node-compatibility-requirement" product="hyperdrive" />
 
 This will allow Hyperdrive to generate a dynamic connection string within your Worker that you can pass to your existing database driver. Refer to [Driver examples](#driver-examples) to learn how to set up a database driver with Hyperdrive.
 
@@ -105,57 +93,9 @@ The following Workers code shows you how to use [mysql2](https://github.com/sido
 
 ### `mysql`
 
-Install the `mysql` driver:
+The following Workers code shows you how to use [mysql](https://github.com/mysqljs/mysql) with Hyperdrive.
 
-```sh
-npm install mysql
-```
-
-**Ensure you have `compatibility_flags` and `compatibility_date` set in your [Wrangler configuration file](/workers/wrangler/configuration/)** as shown below:
-
-<Render file="nodejs-compat-wrangler-toml" product="workers" />
-
-Create a new connection and pass the Hyperdrive parameters:
-
-```ts
-import { createConnection } from "mysql";
-
-export interface Env {
-	HYPERDRIVE: Hyperdrive;
-}
-
-export default {
-	async fetch(request, env, ctx): Promise<Response> {
-		const result = await new Promise<any>((resolve) => {
-			const connection = createConnection({
-				host: env.HYPERDRIVE.host,
-				user: env.HYPERDRIVE.user,
-				password: env.HYPERDRIVE.password,
-				database: env.HYPERDRIVE.database,
-				port: env.HYPERDRIVE.port,
-			});
-
-			connection.connect((error: { message: string }) => {
-				if (error) {
-					throw new Error(error.message);
-				}
-
-				connection.query("SHOW tables;", [], (error, rows, fields) => {
-					connection.end();
-
-					resolve({ fields, rows });
-				});
-			});
-		});
-
-		return new Response(JSON.stringify(result), {
-			headers: {
-				"Content-Type": "application/json",
-			},
-		});
-	},
-} satisfies ExportedHandler<Env>;
-```
+<Render file="use-mysql-to-make-query" product="hyperdrive" />
 
 ## Identify connections from Hyperdrive
 

src/content/docs/hyperdrive/examples/connect-to-mysql/aws-rds-aurora.mdx renamed to src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/aws-rds-aurora.mdx

@@ -97,3 +97,4 @@ With a database user, password, database endpoint (hostname and port), and datab
 ## 3. Create a database configuration
 
 <Render file="create-hyperdrive-config-mysql" />
+<Render file="create-hyperdrive-config-mysql-next-steps" />

src/content/docs/hyperdrive/examples/connect-to-mysql/azure.mdx renamed to src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/azure.mdx

@@ -38,3 +38,4 @@ To connect to a private Azure Database for MySQL instance, refer to [Connect to
 ## 2. Create a database configuration
 
 <Render file="create-hyperdrive-config-mysql" />
+<Render file="create-hyperdrive-config-mysql-next-steps" />

src/content/docs/hyperdrive/examples/connect-to-mysql/google-cloud-sql.mdx renamed to src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/google-cloud-sql.mdx

@@ -41,3 +41,4 @@ With the username, password, public IP address and (optional) database name (def
 ## 2. Create a database configuration
 
 <Render file="create-hyperdrive-config-mysql" />
+<Render file="create-hyperdrive-config-mysql-next-steps" />

src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/index.mdx

@@ -0,0 +1,14 @@
+---
+type: overview
+pcx_content_type: navigation
+title: Database Providers
+hideChildren: false
+sidebar:
+  order: 5
+  group:
+    hideIndex: true
+---
+
+import { DirectoryListing } from "~/components";
+
+<DirectoryListing />

src/content/docs/hyperdrive/examples/connect-to-mysql/planetscale.mdx renamed to src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale.mdx

@@ -27,3 +27,11 @@ With the host, database name, username and password, you can now create a Hyperd
 ## 2. Create a database configuration
 
 <Render file="create-hyperdrive-config-mysql" />
+
+:::note
+
+When connecting to a Planetscale database with Hyperdrive, you should use a driver like [node-postgres (pg)](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/) or [Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/) to connect directly to the underlying database instead of the [Planetscale serverless driver](https://planetscale.com/docs/tutorials/planetscale-serverless-driver). Hyperdrive is optimized for database access for Workers and will perform global connection pooling and fast query routing by connecting directly to your database.
+
+:::
+
+<Render file="create-hyperdrive-config-mysql-next-steps" />

src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx

@@ -0,0 +1,167 @@
+---
+pcx_content_type: example
+title: Drizzle ORM
+sidebar:
+  order: 3
+meta:
+  title: Using Drizzle ORM with Hyperdrive for MySQL
+---
+
+import { Render, Steps } from "~/components";
+
+[Drizzle ORM](https://orm.drizzle.team/) is a lightweight TypeScript ORM with a focus on type safety. This example demonstrates how to use Drizzle ORM with MySQL via Cloudflare Hyperdrive in a Workers application.
+
+## Prerequisites
+
+- A Cloudflare account with Workers access
+- A MySQL database
+- A [Hyperdrive configuration to your MySQL database](/hyperdrive/get-started/#3-connect-hyperdrive-to-a-database)
+
+## 1. Install Drizzle
+
+Install the Drizzle ORM and its dependencies such as the [mysql2](https://github.com/sidorares/node-mysql2) driver:
+
+```sh
+# mysql2 v3.13.0 or later is required
+npm i drizzle-orm mysql2 dotenv
+npm i -D drizzle-kit tsx @types/node
+```
+
+Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file:
+
+<Render file="hyperdrive-node-compatibility-requirement" product="hyperdrive"/>
+
+## 2. Configure Drizzle
+
+### 2.1. Define a schema
+
+With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL.
+
+<Steps>
+1. Create a folder `/db/` in `/src/`.
+2. Create a `schema.ts` file.
+3. In `schema.ts`, define a `users` table as shown below.
+
+	```ts title="src/db/schema.ts"
+	// src/schema.ts
+	import { mysqlTable, int, varchar, timestamp } from "drizzle-orm/mysql-core";
+
+	export const users = mysqlTable("users", {
+		id: int("id").primaryKey().autoincrement(),
+		name: varchar("name", { length: 255 }).notNull(),
+		email: varchar("email", { length: 255 }).notNull().unique(),
+		createdAt: timestamp("created_at").defaultNow(),
+	});
+	```
+</Steps>
+
+### 2.2. Connect Drizzle ORM to the database with Hyperdrive
+
+Use your the credentials of your Hyperdrive configuration for your database when using the Drizzle ORM.
+
+Populate your `index.ts` file as shown below.
+
+```ts title="src/index.ts"
+// src/index.ts
+
+import { drizzle } from "drizzle-orm/mysql2";
+import { createConnection } from "mysql2";
+import { users } from "./db/schema";
+
+export interface Env {
+	HYPERDRIVE: Hyperdrive;
+  }
+
+export default {
+	async fetch(request, env, ctx): Promise<Response> {
+		// Create a connection using the mysql2 driver with the Hyperdrive credentials (only accessible from your Worker).
+		const connection = await createConnection({
+			host: env.HYPERDRIVE.host,
+			user: env.HYPERDRIVE.user,
+			password: env.HYPERDRIVE.password,
+			database: env.HYPERDRIVE.database,
+			port: env.HYPERDRIVE.port,
+
+			// Required to enable mysql2 compatibility for Workers
+			disableEval: true,
+		});
+
+		// Create the Drizzle client with the mysql2 driver connection
+		const db = drizzle(connection);
+
+		// Sample query to get all users
+		const allUsers = await db.select().from(users);
+
+		return Response.json(allUsers);
+	},
+} satisfies ExportedHandler<Env>;
+```
+
+### 2.3. Configure Drizzle-Kit for migrations (optional)
+
+:::note
+You need to set up the tables in your database so that Drizzle ORM can make queries that work.
+
+If you have already set it up (for example, if another user has applied the schema to your database), or if you are starting to use Drizzle ORM and the schema matches what already exists in your database, then you do not need to run the migration.
+:::
+
+You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/mysql-new) for additional guidance.
+
+<Steps>
+1. Create a `.env` file in the root folder of your project, and add your database connection string. The Drizzle Kit CLI will use this connection string to create and apply the migrations.
+
+   ```toml title=".env"
+   # .env
+   # Replace with your direct database connection string
+   DATABASE_URL='mysql://user:[email protected]/database-name'
+   ```
+
+2. Create a `drizzle.config.ts` file in the root folder of your project to configure Drizzle Kit and add the following content:
+
+   ```ts title="drizzle.config.ts"
+   import 'dotenv/config';
+   import { defineConfig } from 'drizzle-kit';
+   export default defineConfig({
+   out: './drizzle',
+   schema: './src/db/schema.ts',
+   dialect: 'mysql',
+   dbCredentials: {
+   url: process.env.DATABASE_URL!,
+     },
+   });
+   ```
+
+3. Generate the migration file for your database according to your schema files and apply the migrations to your database.
+
+   ```bash
+   npx drizzle-kit generate
+   ```
+   ```bash output
+   No config path provided, using default 'drizzle.config.ts'
+   Reading config file 'drizzle.config.ts'
+   Reading schema files:
+   /src/db/schema.ts
+
+   1 tables
+   users 4 columns 0 indexes 0 fks
+
+   [✓] Your SQL migration file ➜ drizzle/0000_daffy_rhodey.sql 🚀
+   ```
+   ```bash
+   npx drizzle-kit migrate
+   ```
+   ```bash output
+   No config path provided, using default 'drizzle.config.ts'
+   Reading config file 'drizzle.config.ts'
+   ```
+</Steps>
+
+## 3. Deploy your Worker
+
+Deploy your Worker.
+
+```bash
+npx wrangler deploy
+```
+
+<Render file="create-hyperdrive-config-next-steps" product="hyperdrive" />

src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/index.mdx

@@ -0,0 +1,12 @@
+---
+pcx_content_type: navigation
+title: Libraries and Drivers
+sidebar:
+  order: 8
+  group:
+    hideIndex: true
+---
+
+import { DirectoryListing } from "~/components";
+
+<DirectoryListing />