diff --git a/src/content/docs/hyperdrive/configuration/connect-to-postgres.mdx b/src/content/docs/hyperdrive/configuration/connect-to-postgres.mdx index ec3c878aac486f8..24baf469101b757 100644 --- a/src/content/docs/hyperdrive/configuration/connect-to-postgres.mdx +++ b/src/content/docs/hyperdrive/configuration/connect-to-postgres.mdx @@ -52,18 +52,24 @@ Refer to the [Examples documentation](/hyperdrive/examples/) for step-by-step gu Hyperdrive uses Workers [TCP socket support](/workers/runtime-apis/tcp-sockets/#connect) to support TCP connections to databases. The following table lists the supported database drivers and the minimum version that works with Hyperdrive: -| 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. | -| 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`^ | | -| [rust-postgres](https://github.com/sfackler/rust-postgres) | [rust-postgres documentation](https://docs.rs/postgres/latest/postgres/) | `v0.19.8` | Use the [`query_typed`](https://docs.rs/postgres/latest/postgres/struct.Client.html#method.query_typed) method for best performance. | +| 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. | +| 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`^ | | +| [rust-postgres](https://github.com/sfackler/rust-postgres) | [rust-postgres documentation](https://docs.rs/postgres/latest/postgres/) | `v0.19.8` | Use the [`query_typed`](https://docs.rs/postgres/latest/postgres/struct.Client.html#method.query_typed) method for best performance. | ^ _The marked libraries use `node-postgres` as a dependency._ Other drivers and ORMs not listed may also be supported: this list is not exhaustive. +### Database drivers and Node.js compatibility + +[Node.js compatibility](/workers/runtime-apis/nodejs/) is required for database drivers, including Postgres.js, and needs to be configured for your Workers project. + + + ## Supported TLS (SSL) modes Hyperdrive supports the following [PostgreSQL TLS (SSL)](https://www.postgresql.org/docs/current/libpq-ssl.html) connection modes when connecting to your origin database: diff --git a/src/content/docs/hyperdrive/get-started.mdx b/src/content/docs/hyperdrive/get-started.mdx index c172656857ce97a..720ab34eac42a0f 100644 --- a/src/content/docs/hyperdrive/get-started.mdx +++ b/src/content/docs/hyperdrive/get-started.mdx @@ -74,23 +74,11 @@ This will create a new `hyperdrive-tutorial` directory. Your new `hyperdrive-tut - A `"Hello World"` [Worker](/workers/get-started/guide/#3-write-code) at `src/index.ts`. - A [`wrangler.toml`](/workers/wrangler/configuration/) configuration file. `wrangler.toml` is how your `hyperdrive-tutorial` Worker will connect to Hyperdrive. -:::note - -Note that the `wrangler.toml` file contains the following option: - -import { WranglerConfig } from "~/components"; - - +### Enable Node.js compatibility -```toml title="wrangler.toml" -compatibility_flags = [ "nodejs_compat" ] -``` - - +[Node.js compatibility](/workers/runtime-apis/nodejs/) is required for database drivers, including Postgres.js, and needs to be configured for your Workers project. -This enables the Node.js compatibility mode which is required for database drivers, including Postgres.js. - -::: + ## 3. Connect Hyperdrive to a database diff --git a/src/content/docs/workers/configuration/compatibility-flags.mdx b/src/content/docs/workers/configuration/compatibility-flags.mdx index df1c1de34622207..10a4bb927fc8277 100644 --- a/src/content/docs/workers/configuration/compatibility-flags.mdx +++ b/src/content/docs/workers/configuration/compatibility-flags.mdx @@ -45,17 +45,11 @@ Compatibility flags can be set when uploading a Worker using the [Workers Script ## Node.js compatibility flag -:::note -You can opt into improved Node.js compatibility by using `nodejs_compat_v2` instead of `nodejs_compat`. This provides the functionality of `nodejs_compat`, but -additionally you can import Node.js modules without the `node:` prefix and use polyfilled Node.js modules and globals that are not available with `nodejs_compat`. - -On September 23, 2024, `nodejs_compat` will use the improved Node.js compatibility currently enabled with `nodejs_compat_v2`. This will require updating your -compatibility_date to 2024-09-23 or later. -::: - -A [growing subset](/workers/runtime-apis/nodejs/) of Node.js APIs are available directly as [Runtime APIs](/workers/runtime-apis/nodejs), with no need to add polyfills to your own code. To enable these APIs in your Worker, add the `nodejs_compat` compatibility flag to your `wrangler.toml`: +import { Render } from "~/components"; + +A [growing subset](/workers/runtime-apis/nodejs/) of Node.js APIs are available directly as [Runtime APIs](/workers/runtime-apis/nodejs), with no need to add polyfills to your own code. To enable these APIs in your Worker, only the `nodejs_compat` compatibility flag is required: @@ -69,8 +63,6 @@ As additional Node.js APIs are added, they will be made available under the `nod The Node.js `AsyncLocalStorage` API is a particularly useful feature for Workers. To enable only the `AsyncLocalStorage` API, use the `nodejs_als` compatibility flag. - - ```toml title="wrangler.toml" diff --git a/src/content/docs/workers/runtime-apis/nodejs/index.mdx b/src/content/docs/workers/runtime-apis/nodejs/index.mdx index 4918c7dd8e1191d..fcfa2b566a089a1 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/index.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/index.mdx @@ -18,22 +18,9 @@ You can view which APIs are supported using the [Node.js compatability matrix](h ## Get Started -To enable both built-in runtime APIs and polyfills for your Worker or Pages project, add the [`nodejs_compat`](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) [compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) to your `wrangler.toml`, and set your compatibility date to September 23rd, 2024 or later. +import { Render } from "~/components"; -import { WranglerConfig } from "~/components"; - - - -```toml title="wrangler.toml" -compatibility_flags = [ "nodejs_compat" ] -compatibility_date = "2024-09-23" -``` - - - -:::note -As of September 23rd, 2024, the `nodejs_compat` compatibility flag enables the exact same behavior as the `nodejs_compat_v2` compatibility flag, as long as your compatibility date is set to September 23rd, 2024 or later. -::: + ## Built-in Node.js Runtime APIs @@ -68,7 +55,7 @@ If an API you wish to use is missing and you want to suggest that Workers suppor To enable only the Node.js `AsyncLocalStorage` API, use the `nodejs_als` compatibility flag. - +import { WranglerConfig } from "~/components"; diff --git a/src/content/docs/workers/tutorials/postgres/index.mdx b/src/content/docs/workers/tutorials/postgres/index.mdx index caac9a4cd70f904..84053c1c725cfbf 100644 --- a/src/content/docs/workers/tutorials/postgres/index.mdx +++ b/src/content/docs/workers/tutorials/postgres/index.mdx @@ -13,7 +13,7 @@ languages: - SQL --- -import { Render, PackageManagers } from "~/components"; +import { Render, PackageManagers, WranglerConfig } from "~/components"; In this tutorial, you will learn how to create a Cloudflare Workers application and connect it to a PostgreSQL database using [TCP Sockets](/workers/runtime-apis/tcp-sockets/) and [Hyperdrive](/hyperdrive/). The Workers application you create in this tutorial will interact with a product database inside of PostgreSQL. @@ -58,17 +58,9 @@ cd postgres-tutorial ### Enable Node.js compatibility - +[Node.js compatibility](/workers/runtime-apis/nodejs/) is required for database drivers, including Postgres.js, and needs to be configured for your Workers project. -import { WranglerConfig } from "~/components"; - - - -```toml title="wrangler.toml" -compatibility_flags = ["nodejs_compat_v2"] -``` - - + ## 2. Add the PostgreSQL connection library @@ -112,8 +104,6 @@ npx wrangler secret put DB_URL Set your `DB_URL` secret locally in a `.dev.vars` file as documented in [Local Development with Secrets](/workers/configuration/secrets/). - - ```toml @@ -126,8 +116,6 @@ DB_URL="" Configure each database parameter as an [environment variable](/workers/configuration/environment-variables/) via the [Cloudflare dashboard](/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard) or in your `wrangler.toml` file. Refer to an example of a`wrangler.toml` file configuration: - - ```toml @@ -329,8 +317,6 @@ You can also use explicit parameters by following the [wrangler documentation fo This command outputs the Hyperdrive configuration `id` that will be used for your Hyperdrive [binding](/workers/runtime-apis/bindings/). Set up your binding by specifying the `id` in the `wrangler.toml` file. - - ```toml {7-9} diff --git a/src/content/partials/workers/nodejs_compat.mdx b/src/content/partials/workers/nodejs_compat.mdx new file mode 100644 index 000000000000000..24abe03f666b6fb --- /dev/null +++ b/src/content/partials/workers/nodejs_compat.mdx @@ -0,0 +1,20 @@ +--- +{} +--- + +import { WranglerConfig } from "~/components"; + +To enable both built-in runtime APIs and polyfills for your Worker or Pages project, add the [`nodejs_compat`](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) [compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) to your `wrangler.toml`, and set your compatibility date to September 23rd, 2024 or later. + + + +```toml title="wrangler.toml" +compatibility_flags = [ "nodejs_compat" ] +compatibility_date = "2024-09-23" +``` + + + +:::note +As of September 23rd, 2024, the `nodejs_compat` compatibility flag enables the exact same behavior as the `nodejs_compat_v2` compatibility flag, as long as your compatibility date is set to September 23rd, 2024 or later. +:::