diff --git a/public/__redirects b/public/__redirects index 22184a143de584c..c245dcc94100220 100644 --- a/public/__redirects +++ b/public/__redirects @@ -1690,26 +1690,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 diff --git a/src/content/docs/hyperdrive/configuration/connect-to-private-database.mdx b/src/content/docs/hyperdrive/configuration/connect-to-private-database.mdx index 67c603bd6d7368e..94533499ae63807 100644 --- a/src/content/docs/hyperdrive/configuration/connect-to-private-database.mdx +++ b/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. - + Now, deploy your Worker: diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/index.mdx index 7ca8964c52605fc..f1da4356b4b152c 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/index.mdx +++ b/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: - - -```toml -# required for database drivers to function -compatibility_flags = ["nodejs_compat"] -compatibility_date = "2024-09-23" - -[[hyperdrive]] -binding = "HYPERDRIVE" -id = "" -``` - - + 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: - - - -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 { - const result = await new Promise((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; -``` + ## Identify connections from Hyperdrive diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/aws-rds-aurora.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/aws-rds-aurora.mdx similarity index 98% rename from src/content/docs/hyperdrive/examples/connect-to-mysql/aws-rds-aurora.mdx rename to src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/aws-rds-aurora.mdx index 207799ee4113900..feee9b1f413f545 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/aws-rds-aurora.mdx +++ b/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 + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/azure.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/azure.mdx similarity index 96% rename from src/content/docs/hyperdrive/examples/connect-to-mysql/azure.mdx rename to src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/azure.mdx index 33de0b0bd3e96c0..db66a9deef1cdec 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/azure.mdx +++ b/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 + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/google-cloud-sql.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/google-cloud-sql.mdx similarity index 96% rename from src/content/docs/hyperdrive/examples/connect-to-mysql/google-cloud-sql.mdx rename to src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/google-cloud-sql.mdx index c446f01dd8b8c1d..8969f2feeae0216 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/google-cloud-sql.mdx +++ b/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 + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/index.mdx new file mode 100644 index 000000000000000..f91f8e5e15c8f22 --- /dev/null +++ b/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"; + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/planetscale.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale.mdx similarity index 64% rename from src/content/docs/hyperdrive/examples/connect-to-mysql/planetscale.mdx rename to src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale.mdx index 6330eb71943e2aa..eee8792368b9e24 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-mysql/planetscale.mdx +++ b/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 + +:::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. + +::: + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm.mdx new file mode 100644 index 000000000000000..99cb93fd7439f00 --- /dev/null +++ b/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: + + + +## 2. Configure Drizzle + +### 2.1. Define a schema + +With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL. + + +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(), + }); + ``` + + +### 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 { + // 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; +``` + +### 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. + + +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:password@db-host.cloud/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' + ``` + + +## 3. Deploy your Worker + +Deploy your Worker. + +```bash +npx wrangler deploy +``` + + \ No newline at end of file diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/index.mdx new file mode 100644 index 000000000000000..591fb248c977c95 --- /dev/null +++ b/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"; + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql.mdx new file mode 100644 index 000000000000000..0e76bbb27c87778 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql.mdx @@ -0,0 +1,15 @@ +--- +pcx_content_type: example +title: mysql +sidebar: + order: 2 +meta: + title: Using mysql driver with Hyperdrive +--- + +import { Render } from "~/components"; + +The [mysql](https://github.com/mysqljs/mysql) package is a MySQL driver for Node.js. +This example demonstrates how to use it with Cloudflare Workers and Hyperdrive. + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql2.mdx b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql2.mdx new file mode 100644 index 000000000000000..ba488788cc08a38 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql2.mdx @@ -0,0 +1,13 @@ +--- +pcx_content_type: example +title: mysql2 +sidebar: + order: 1 +--- + +import { Render } from "~/components"; + +The [mysql2](https://github.com/sidorares/node-mysql2) package is a modern MySQL driver for Node.js with better performance and built-in Promise support. +This example demonstrates how to use it with Cloudflare Workers and Hyperdrive. + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx index e4a9a590490e741..5448a53f6c80a7a 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx @@ -32,19 +32,7 @@ npx wrangler hyperdrive create my-first-hyperdrive --connection-string="postgres 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: - - -```toml -# required for database drivers to function -compatibility_flags = ["nodejs_compat"] -compatibility_date = "2024-09-23" - -[[hyperdrive]] -binding = "HYPERDRIVE" -id = "" -``` - - + 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. @@ -56,7 +44,7 @@ Hyperdrive uses Workers [TCP socket support](/workers/runtime-apis/tcp-sockets/# | Driver | Documentation | Minimum Version Required | Notes | | ---------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Postgres.js (**recommended**) | [Postgres.js documentation](https://github.com/porsager/postgres) | `postgres@3.4.4` | Supported in both Workers & Pages. | +| Postgres.js | [Postgres.js documentation](https://github.com/porsager/postgres) | `postgres@3.4.4` | Supported in both Workers & Pages. | | node-postgres - `pg` | [node-postgres - `pg` documentation](https://node-postgres.com/) | `pg@8.13.0` | `8.11.4` introduced a bug with URL parsing and will not work. `8.11.5` fixes this. Requires `compatibility_flags = ["nodejs_compat"]` and `compatibility_date = "2024-09-23"` - refer to [Node.js compatibility](/workers/runtime-apis/nodejs). Requires wrangler `3.78.7` or later. | | Drizzle | [Drizzle documentation](https://orm.drizzle.team/) | `0.26.2`^ | | | Kysely | [Kysely documentation](https://kysely.dev/) | `0.26.3`^ | | @@ -84,57 +72,13 @@ The following examples show you how to: The following Workers code shows you how to use [Postgres.js](https://github.com/porsager/postgres) with Hyperdrive. - + ### node-postgres / pg Install the `node-postgres` driver: -```sh -npm install pg -``` - -**Ensure you have `compatibility_flags` and `compatibility_date` set in your [Wrangler configuration file](/workers/wrangler/configuration/)** as shown below: - - - -Create a new `Client` instance and pass the Hyperdrive parameters: - -```ts -import { Client } from "pg"; - -export interface Env { - // If you set another name in the Wrangler configuration file as the value for 'binding', - // replace "HYPERDRIVE" with the variable name you defined. - HYPERDRIVE: Hyperdrive; -} - -export default { - async fetch(request, env, ctx): Promise { - const client = new Client({ - connectionString: env.HYPERDRIVE.connectionString, - }); - - try { - // Connect to your database - await client.connect(); - - // A very simple test query - const result = await client.query({ text: "SELECT * FROM pg_tables" }); - - // Clean up the client, ensuring we don't kill the worker before that is - // completed. - ctx.waitUntil(client.end()); - - // Return result rows as JSON - return Response.json({ result: result }); - } catch (e) { - console.log(e); - return Response.json({ error: e.message }, { status: 500 }); - } - }, -} satisfies ExportedHandler; -``` + ## Identify connections from Hyperdrive diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/aws-rds-aurora.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora.mdx similarity index 98% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/aws-rds-aurora.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora.mdx index 5446dbf36096855..fd21e2dc5b028d4 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/aws-rds-aurora.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora.mdx @@ -91,3 +91,4 @@ With a database user, password, database endpoint (hostname and port) and databa ## 3. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/azure.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/azure.mdx similarity index 96% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/azure.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/azure.mdx index 9edf6ec42a57bb7..24f42672b188a4a 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/azure.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/azure.mdx @@ -38,3 +38,4 @@ To connect to a private Azure Database for PostgreSQL instance, refer to [Connec ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/cockroachdb.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb.mdx similarity index 97% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/cockroachdb.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb.mdx index 1447ad8f64cb644..3ca5d23a131ad58 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/cockroachdb.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb.mdx @@ -41,3 +41,4 @@ By default, the CockroachDB cloud enables connections from the public Internet ( ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/digital-ocean.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/digital-ocean.mdx similarity index 96% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/digital-ocean.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/digital-ocean.mdx index c37f8eb30111ff5..5010d0ec4f5c099 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/digital-ocean.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/digital-ocean.mdx @@ -29,6 +29,7 @@ With the connection string, you can now create a Hyperdrive database configurati ## 2. Create a database configuration + :::note If you see a DNS-related error, it is possible that the DNS for your vendor's database has not yet been propagated. Try waiting 10 minutes before retrying the operation. Refer to [DigitalOcean support page](https://docs.digitalocean.com/support/why-does-my-domain-fail-to-resolve/) for more information. diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/fly.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly.mdx similarity index 97% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/fly.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly.mdx index 1074dbf1a29e824..567b5ba464391d8 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/fly.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly.mdx @@ -62,3 +62,4 @@ You can connect Hyperdrive to any existing Fly database by: ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/google-cloud-sql.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/google-cloud-sql.mdx similarity index 98% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/google-cloud-sql.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/google-cloud-sql.mdx index cdefec657b84a58..7563fd076ef22d9 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/google-cloud-sql.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/google-cloud-sql.mdx @@ -61,3 +61,4 @@ Refer to [Google Cloud's documentation](https://cloud.google.com/sql/docs/postgr ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/index.mdx new file mode 100644 index 000000000000000..f91f8e5e15c8f22 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-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"; + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/materialize.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize.mdx similarity index 97% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/materialize.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize.mdx index 2290a0678609931..ece14edd5ad15cf 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/materialize.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize.mdx @@ -43,3 +43,4 @@ With the username, app password, hostname, port and database name, you can now c ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/neon.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon.mdx similarity index 69% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/neon.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon.mdx index 9e104549698ad74..53b3d68f8c6d923 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/neon.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon.mdx @@ -28,3 +28,11 @@ With both the connection string and the password, you can now create a Hyperdriv ## 2. Create a database configuration + +:::note + +When connecting to a Neon 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 [Neon serverless driver](https://neon.tech/docs/serverless/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. + +::: + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/nile.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/nile.mdx similarity index 96% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/nile.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/nile.mdx index 12cca7c471d5281..d0cb043b746f4ef 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/nile.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/nile.mdx @@ -39,3 +39,4 @@ With the connection string, you can now create a Hyperdrive database configurati ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/pgedge.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/pgedge.mdx similarity index 95% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/pgedge.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/pgedge.mdx index fa6f3487f25ea6b..8413afda667b797 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/pgedge.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/pgedge.mdx @@ -26,3 +26,4 @@ To retrieve your connection string from the pgEdge dashboard: ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/supabase.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase.mdx similarity index 65% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/supabase.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase.mdx index bb80699588f5e14..df8d1184c0c4c72 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/supabase.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase.mdx @@ -31,3 +31,11 @@ With a database user, password, database endpoint (hostname and port) and databa ## 2. Create a database configuration + +:::note + +When connecting to a Supabase 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 [Supabase JavaScript client](https://github.com/supabase/supabase-js). Hyperdrive is optimized for database access for Workers and will perform global connection pooling and fast query routing by connecting directly to your database. + +::: + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/timescale.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale.mdx similarity index 97% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/timescale.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale.mdx index bdb88a6d9919170..20d3590afaa9132 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/timescale.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale.mdx @@ -45,3 +45,4 @@ With the connection string, you can now create a Hyperdrive database configurati ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/xata.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata.mdx similarity index 94% rename from src/content/docs/hyperdrive/examples/connect-to-postgres/xata.mdx rename to src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata.mdx index e595cf5ab933df9..134003936861283 100644 --- a/src/content/docs/hyperdrive/examples/connect-to-postgres/xata.mdx +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata.mdx @@ -28,3 +28,4 @@ To retrieve your connection string from the Xata dashboard: ## 2. Create a database configuration + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx new file mode 100644 index 000000000000000..53605c7085db2ce --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm.mdx @@ -0,0 +1,172 @@ +--- +pcx_content_type: example +title: Drizzle ORM +sidebar: + order: 3 +meta: + title: Using Drizzle ORM with Hyperdrive for PostgreSQL +--- + +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 PostgreSQL via Cloudflare Hyperdrive in a Workers application. + +## Prerequisites + +- A Cloudflare account with Workers access +- A PostgreSQL database +- A [Hyperdrive configuration to your PostgreSQL database](/hyperdrive/get-started/#3-connect-hyperdrive-to-a-database) + +## 1. Install Drizzle + +Install the Drizzle ORM and its dependencies such as the [postgres](https://github.com/porsager/postgres) driver: + +```sh +# postgres 3.4.5 or later is recommended +npm i drizzle-orm postgres dotenv +npm i -D drizzle-kit tsx @types/node +``` + +Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: + + + +## 2. Configure Drizzle + +### 2.1. Define a schema + +With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL. + + +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/db/schema.ts + import { pgTable, serial, varchar, timestamp } from "drizzle-orm/pg-core"; + + export const users = pgTable("users", { + id: serial("id").primaryKey(), + name: varchar("name", { length: 255 }).notNull(), + email: varchar("email", { length: 255 }).notNull().unique(), + createdAt: timestamp("created_at").defaultNow(), + }); + ``` + + +### 2.2. Connect Drizzle ORM to the database with Hyperdrive + +Use 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/postgres-js"; +import postgres from "postgres"; +import { users } from "./db/schema"; + +export interface Env { + HYPERDRIVE: Hyperdrive; +} + +export default { + async fetch(request, env, ctx): Promise { + // Create a database client with postgres.js driver connected via Hyperdrive + const sql = postgres(env.HYPERDRIVE.connectionString, { + // Limit the connections for the Worker request to 5 due to Workers' limits on concurrent external connections + max: 5, + // If you are not using array types in your Postgres schema, disable `fetch_types` to avoid an additional round-trip (unnecessary latency) + fetch_types: false, + }); + + // Create the Drizzle client with the postgres.js connection + const db = drizzle(sql); + + // Sample query to get all users + const allUsers = await db.select().from(users); + + // Clean up the connection + ctx.waitUntil(sql.end()); + + return Response.json(allUsers); + }, +} satisfies ExportedHandler; +``` + +:::note +You may use [node-postgres](https://orm.drizzle.team/docs/get-started-postgresql#node-postgres) or [Postgres.js](https://orm.drizzle.team/docs/get-started-postgresql#postgresjs) +when using Drizzle ORM. Both are supported and compatible. +::: + +### 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/postgresql-new) for additional guidance. + + +1. Create a `.env` file 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='postgres://user:password@db-host.cloud/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" + // drizzle.config.ts + import "dotenv/config"; + import { defineConfig } from "drizzle-kit"; + export default defineConfig({ + out: "./drizzle", + schema: "./src/db/schema.ts", + dialect: "postgresql", + 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. + + Run the following two commands: + + ```bash + npx drizzle-kit generate + ``` + ```bash output + No config path provided, using default 'drizzle.config.ts' + Reading config file 'drizzle.config.ts' + 1 tables + users 4 columns 0 indexes 0 fks + + [✓] Your SQL migration file ➜ drizzle/0000_mysterious_queen_noir.sql 🚀 + ``` + + ```bash + npx drizzle-kit migrate + ``` + ```bash output + No config path provided, using default 'drizzle.config.ts' + Reading config file 'drizzle.config.ts' + Using 'postgres' driver for database querying + ``` + + +## 3. Deploy your Worker + +Deploy your Worker. + +```bash +npx wrangler deploy +``` + + \ No newline at end of file diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/index.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/index.mdx new file mode 100644 index 000000000000000..591fb248c977c95 --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-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"; + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres.mdx new file mode 100644 index 000000000000000..8cc2e3a61b699cd --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres.mdx @@ -0,0 +1,14 @@ +--- +pcx_content_type: example +title: node-postgres (pg) +sidebar: + order: 1 +meta: + title: Using node-postgres with Hyperdrive +--- + +import { Render } from "~/components"; + +[node-postgres](https://node-postgres.com/) (pg) is a widely-used PostgreSQL driver for Node.js applications. This example demonstrates how to use node-postgres with Cloudflare Hyperdrive in a Workers application. + + diff --git a/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js.mdx b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js.mdx new file mode 100644 index 000000000000000..8792a7a33b05f3f --- /dev/null +++ b/src/content/docs/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js.mdx @@ -0,0 +1,14 @@ +--- +pcx_content_type: example +title: Postgres.js +sidebar: + order: 2 +meta: + title: Using Postgres.js with Hyperdrive +--- + +import { Render } from "~/components"; + +[Postgres.js](https://github.com/porsager/postgres) is a modern, fully-featured PostgreSQL driver for Node.js. This example demonstrates how to use Postgres.js with Cloudflare Hyperdrive in a Workers application. + + diff --git a/src/content/docs/hyperdrive/reference/supported-databases-and-features.mdx b/src/content/docs/hyperdrive/reference/supported-databases-and-features.mdx index de7057d8f63bdfd..1f86026ee9b4b07 100644 --- a/src/content/docs/hyperdrive/reference/supported-databases-and-features.mdx +++ b/src/content/docs/hyperdrive/reference/supported-databases-and-features.mdx @@ -18,18 +18,18 @@ The following table shows which database engines and/or specific database provid ## Supported database providers -Hyperdrive supports managed Postgres and MySQL databases provided by various providers, including AWS, Azure, and GCP. Refer to [Examples](/hyperdrive/examples/connect-to-postgres/) to see how to connect to various database providers. +Hyperdrive supports managed Postgres and MySQL databases provided by various providers, including AWS, Azure, and GCP. Refer to [Examples](/hyperdrive/examples/connect-to-postgres/) to see how to connect to various database providers. Hyperdrive also supports databases that are compatible with the Postgres or MySQL protocol. The following is a non-exhaustive list of Postgres or MySQL-compatible database providers: | Database Engine | Supported | Known supported versions | Details | | --------------- | --------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ | -| AWS Aurora | ✅ | All | Postgres-compatible and MySQL-compatible. Refer to AWS Aurora examples for [MySQL](/hyperdrive/examples/connect-to-mysql/aws-rds-aurora/) and [Postgres](/hyperdrive/examples/connect-to-postgres/aws-rds-aurora/). | +| AWS Aurora | ✅ | All | Postgres-compatible and MySQL-compatible. Refer to AWS Aurora examples for [MySQL](/hyperdrive/examples/connect-to-mysql/mysql-database-providers/aws-rds-aurora/) and [Postgres](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora/). | | Neon | ✅ | All | Neon currently runs Postgres 15.x | | Supabase | ✅ | All | Supabase currently runs Postgres 15.x | -| Timescale | ✅ | All | See the [Timescale guide](/hyperdrive/examples/connect-to-postgres/timescale/) to connect. | -| Materialize | ✅ | All | Postgres-compatible. Refer to the [Materialize guide](/hyperdrive/examples/connect-to-postgres/materialize/) to connect. | -| CockroachDB | ✅ | All | Postgres-compatible. Refer to the [CockroachDB](/hyperdrive/examples/connect-to-postgres/cockroachdb/) guide to connect. | +| Timescale | ✅ | All | See the [Timescale guide](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale/) to connect. | +| Materialize | ✅ | All | Postgres-compatible. Refer to the [Materialize guide](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize/) to connect. | +| CockroachDB | ✅ | All | Postgres-compatible. Refer to the [CockroachDB](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb/) guide to connect. | | Planetscale | ✅ | All | Planetscale currently runs MySQL 8.x | | MariaDB | ✅ | All | MySQL-compatible. | diff --git a/src/content/docs/workers/databases/connecting-to-databases.mdx b/src/content/docs/workers/databases/connecting-to-databases.mdx index 674fd21b3e944f3..a35b55a8a17c8d0 100644 --- a/src/content/docs/workers/databases/connecting-to-databases.mdx +++ b/src/content/docs/workers/databases/connecting-to-databases.mdx @@ -26,7 +26,7 @@ D1 is Cloudflare's own SQL-based, serverless database. It is optimized for globa Traditional databases use SQL drivers that use [TCP sockets](/workers/runtime-apis/tcp-sockets/) to connect to the database. TCP is the de-facto standard protocol that many databases, such as PostgreSQL and MySQL, use for client connectivity. These drivers are also widely compatible with your preferred ORM libraries and query builders. -This also includes serverless databases that are PostgreSQL or MySQL-compatible like [Supabase](/hyperdrive/examples/connect-to-postgres/neon/), [Neon](/hyperdrive/examples/connect-to-postgres/neon/) or [PlanetScale](/hyperdrive/examples/connect-to-mysql/planetscale/), +This also includes serverless databases that are PostgreSQL or MySQL-compatible like [Supabase](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/), [Neon](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon/) or [PlanetScale](/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale/), which can be connected to using both native [TCP sockets and Hyperdrive](/hyperdrive/) or [serverless HTTP-based drivers](/workers/databases/connecting-to-databases/#serverless-databases) (detailed below). | Database | Integration | Library or Driver | Connection Method | diff --git a/src/content/partials/hyperdrive/create-hyperdrive-config-mysql-next-steps.mdx b/src/content/partials/hyperdrive/create-hyperdrive-config-mysql-next-steps.mdx new file mode 100644 index 000000000000000..8d4aea946477409 --- /dev/null +++ b/src/content/partials/hyperdrive/create-hyperdrive-config-mysql-next-steps.mdx @@ -0,0 +1,9 @@ +--- +{} +--- + +## Next steps + +- Learn more about [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/). +- Refer to the [troubleshooting guide](/hyperdrive/observability/troubleshooting/) to debug common issues. +- Understand more about other [storage options](/workers/platform/storage-options/) available to Cloudflare Workers. diff --git a/src/content/partials/hyperdrive/create-hyperdrive-config-mysql.mdx b/src/content/partials/hyperdrive/create-hyperdrive-config-mysql.mdx index eac765e7a356c5d..b05de5035082e05 100644 --- a/src/content/partials/hyperdrive/create-hyperdrive-config-mysql.mdx +++ b/src/content/partials/hyperdrive/create-hyperdrive-config-mysql.mdx @@ -55,9 +55,3 @@ id = "" ## 3. Use Hyperdrive from your Worker - -## Next steps - -- Learn more about [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/). -- Refer to the [troubleshooting guide](/hyperdrive/observability/troubleshooting/) to debug common issues. -- Understand more about other [storage options](/workers/platform/storage-options/) available to Cloudflare Workers. diff --git a/src/content/partials/hyperdrive/create-hyperdrive-config-next-steps.mdx b/src/content/partials/hyperdrive/create-hyperdrive-config-next-steps.mdx new file mode 100644 index 000000000000000..8d4aea946477409 --- /dev/null +++ b/src/content/partials/hyperdrive/create-hyperdrive-config-next-steps.mdx @@ -0,0 +1,9 @@ +--- +{} +--- + +## Next steps + +- Learn more about [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/). +- Refer to the [troubleshooting guide](/hyperdrive/observability/troubleshooting/) to debug common issues. +- Understand more about other [storage options](/workers/platform/storage-options/) available to Cloudflare Workers. diff --git a/src/content/partials/hyperdrive/create-hyperdrive-config.mdx b/src/content/partials/hyperdrive/create-hyperdrive-config.mdx index df47e407458561d..6ea9ab2726db342 100644 --- a/src/content/partials/hyperdrive/create-hyperdrive-config.mdx +++ b/src/content/partials/hyperdrive/create-hyperdrive-config.mdx @@ -51,10 +51,4 @@ id = "" ## 3. Use Hyperdrive from your Worker - - -## Next steps - -- Learn more about [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/). -- Refer to the [troubleshooting guide](/hyperdrive/observability/troubleshooting/) to debug common issues. -- Understand more about other [storage options](/workers/platform/storage-options/) available to Cloudflare Workers. + diff --git a/src/content/partials/hyperdrive/hyperdrive-node-compatibility-requirement.mdx b/src/content/partials/hyperdrive/hyperdrive-node-compatibility-requirement.mdx new file mode 100644 index 000000000000000..4095a504681756f --- /dev/null +++ b/src/content/partials/hyperdrive/hyperdrive-node-compatibility-requirement.mdx @@ -0,0 +1,19 @@ +--- +{} +--- + +import { WranglerConfig } from "~/components"; + + + +```toml +# required for database drivers to function +compatibility_flags = ["nodejs_compat"] +compatibility_date = "2024-09-23" + +[[hyperdrive]] +binding = "HYPERDRIVE" +id = "" +``` + + diff --git a/src/content/partials/hyperdrive/use-mysql-to-make-query.mdx b/src/content/partials/hyperdrive/use-mysql-to-make-query.mdx new file mode 100644 index 000000000000000..5b59fd54b3a420a --- /dev/null +++ b/src/content/partials/hyperdrive/use-mysql-to-make-query.mdx @@ -0,0 +1,56 @@ +--- +{} +--- + +import { Render } from "~/components"; + +Install the [mysql](https://github.com/mysqljs/mysql) driver: + +```sh +npm install mysql +``` + +Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: + + + +Create a new connection and pass the Hyperdrive parameters: + +```ts +import { createConnection } from "mysql"; + +export default { + async fetch(request, env, ctx): Promise { + const result = await new Promise((resolve) => { + // Create a connection using the mysql driver with the Hyperdrive credentials (only accessible from your Worker). + 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); + } + + // Sample query + connection.query("SHOW tables;", [], (error, rows, fields) => { + connection.end(); + + resolve({ fields, rows }); + }); + }); + }); + + // Return result as JSON + return new Response(JSON.stringify(result), { + headers: { + "Content-Type": "application/json", + }, + }); + }, +} satisfies ExportedHandler; +``` diff --git a/src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx b/src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx index 361d32f0b7e1d35..5860e8d38ce76c0 100644 --- a/src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx +++ b/src/content/partials/hyperdrive/use-mysql2-to-make-query.mdx @@ -2,6 +2,8 @@ {} --- +import { Render } from "~/components"; + Install the [mysql2](https://github.com/sidorares/node-mysql2) driver: ```sh @@ -9,22 +11,19 @@ Install the [mysql2](https://github.com/sidorares/node-mysql2) driver: npm install mysql2 ``` +Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: + + + Create a new `connection` instance and pass the Hyperdrive parameters: ```ts // mysql2 v3.13.0 or later is required import { createConnection } from "mysql2/promise"; -export interface Env { - // If you set another name in the Wrangler config file as the value for 'binding', - // replace "HYPERDRIVE" with the variable name you defined. - HYPERDRIVE: Hyperdrive; -} - export default { async fetch(request, env, ctx): Promise { - // Create a connection using the mysql2 driver (or any support driver, ORM or query builder) - // with the Hyperdrive credentials. These credentials are only accessible from your Worker. + // 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, @@ -32,9 +31,7 @@ export default { database: env.HYPERDRIVE.database, port: env.HYPERDRIVE.port, - // The following line is needed for mysql2 compatibility with Workers - // mysql2 uses eval() to optimize result parsing for rows with > 100 columns - // Configure mysql2 to use static parsing instead of eval() parsing with disableEval + // Required to enable mysql2 compatibility for Workers disableEval: true, }); @@ -46,19 +43,16 @@ export default { ctx.waitUntil(connection.end()); // Return result rows as JSON - return new Response(JSON.stringify({ results, fields }), { - headers: { - "Content-Type": "application/json", - "Access-Control-Allow-Origin": "*", - }, - }); + return Response.json({ results, fields }); } catch (e) { console.error(e); - return Response.json( - { error: e instanceof Error ? e.message : e }, - { status: 500 }, - ); } }, } satisfies ExportedHandler; ``` + +:::note + +The minimum version of `mysql2` required for Hyperdrive is `3.13.0`. + +::: diff --git a/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx b/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx new file mode 100644 index 000000000000000..c3f471fd1c92d1c --- /dev/null +++ b/src/content/partials/hyperdrive/use-node-postgres-to-make-query.mdx @@ -0,0 +1,64 @@ +--- +{} +--- + +import { Render } from "~/components"; + +Install the `node-postgres` driver: + +```sh +npm install pg +# If using TypeScript +npm i --save-dev @types/pg +``` + +Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: + + + +Create a new `Client` instance and pass the Hyperdrive `connectionString`: + +```ts +// filepath: src/index.ts +import { Client } from "pg"; + +export default { + async fetch( + request: Request, + env: Env, + ctx: ExecutionContext, + ): Promise { + // Create a new client instance for each request. + const client = new Client({ + connectionString: env.HYPERDRIVE.connectionString, + }); + + try { + // Connect to the database + await client.connect(); + console.log("Connected to PostgreSQL database"); + + // Perform a simple query + const result = await client.query("SELECT * FROM pg_tables"); + + // Clean up the client after the response is returned, before the Worker is killed + env.waitUntil(client.end()); + + return Response.json({ + success: true, + result: result.rows, + }); + } catch (error: any) { + console.error("Database error:", error.message); + + return Response.error(); + } + }, +}; +``` + +:::note + +The minimum version of `node-postgres` required for Hyperdrive is `8.13.0`. + +::: diff --git a/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx b/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx new file mode 100644 index 000000000000000..600d78d51bc6825 --- /dev/null +++ b/src/content/partials/hyperdrive/use-postgres-js-to-make-query.mdx @@ -0,0 +1,62 @@ +--- +{} +--- + +import { Render } from "~/components"; + +Install [Postgres.js](https://github.com/porsager/postgres): + +```sh +# Postgres.js 3.4.5 or later is recommended +npm install postgres +``` + +Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: + + + +Create a Worker that connects to your PostgreSQL database via Hyperdrive: + +```ts +// filepath: src/index.ts +import postgres from "postgres"; + +export default { + async fetch( + request: Request, + env: Env, + ctx: ExecutionContext, + ): Promise { + // Create a database client that connects to your database via Hyperdrive + // using the Hyperdrive credentials + const sql = postgres(env.HYPERDRIVE.connectionString, { + // Limit the connections for the Worker request to 5 due to Workers' limits on concurrent external connections + max: 5, + // If you are not using array types in your Postgres schema, disable `fetch_types` to avoid an additional round-trip (unnecessary latency) + fetch_types: false, + }); + + try { + // A very simple test query + const result = await sql`select * from pg_tables`; + + // Clean up the client, ensuring we don't kill the worker before that is + // completed. + ctx.waitUntil(sql.end()); + + // Return result rows as JSON + return Response.json({ success: true, result: result }); + } catch (e: any) { + console.error("Database error:", e.message); + + return Response.error(); + } + }, +} satisfies ExportedHandler; +``` + +:::note + +The minimum version of `postgres-js` required for Hyperdrive is `3.4.5`. + +::: diff --git a/src/content/partials/hyperdrive/use-postgresjs-to-make-query.mdx b/src/content/partials/hyperdrive/use-postgresjs-to-make-query.mdx deleted file mode 100644 index 4d7782c6fc8bdf9..000000000000000 --- a/src/content/partials/hyperdrive/use-postgresjs-to-make-query.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -{} ---- - -Install the Postgres.js driver: - -```sh -npm install postgres -``` - -Create a new `sql` instance and pass the Hyperdrive parameters: - -```ts -import postgres from "postgres"; - -export interface Env { - // If you set another name in the Wrangler configuration file as the value for 'binding', - // replace "HYPERDRIVE" with the variable name you defined. - HYPERDRIVE: Hyperdrive; -} - -export default { - async fetch(request: Request, env: Env, ctx: ExecutionContext) { - // NOTE: if `prepare: false` is passed when connecting, performance will - // be slower but still correctly supported. - const sql = postgres( - env.HYPERDRIVE.connectionString, - { - // Workers limit the number of concurrent external connections, so be sure to limit - // the size of the local connection pool that postgres.js may establish. - max: 5, - - // If you are using array types in your Postgres schema, it is necessary to fetch - // type information to correctly de/serialize them. However, if you are not using - // those, disabling this will save you an extra round-trip every time you connect. - fetch_types: false, - }, - ); - - try { - // A very simple test query - const result = await sql`select * from pg_tables LIMIT 10`; - - // Clean up the client, ensuring we don't kill the worker before that is - // completed. - ctx.waitUntil(sql.end()); - - // Return result rows as JSON - return Response.json({ result: result }); - } catch (e) { - console.log(e); - return Response.json({ error: e.message }, { status: 500 }); - } - }, -} satisfies ExportedHandler; -``` \ No newline at end of file