Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

adjust db docs for no default nodejs_compat in c3 #19395

Merged
merged 1 commit into from
Jan 24, 2025
Merged

adjust db docs for no default nodejs_compat in c3 #19395

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 13 additions & 7 deletions src/content/docs/hyperdrive/configuration/connect-to-postgres.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) | `[email protected]` | Supported in both Workers & Pages. |
| node-postgres - `pg` | [node-postgres - `pg` documentation](https://node-postgres.com/) | `[email protected]` | `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) | `[email protected]` | Supported in both Workers & Pages. |
| node-postgres - `pg` | [node-postgres - `pg` documentation](https://node-postgres.com/) | `[email protected]` | `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.

<Render file="nodejs_compat" product="workers" />

## 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:
Expand Down
18 changes: 3 additions & 15 deletions src/content/docs/hyperdrive/get-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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";

<WranglerConfig>
### Enable Node.js compatibility

```toml title="wrangler.toml"
compatibility_flags = [ "nodejs_compat" ]
```

</WranglerConfig>
[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.

:::
<Render file="nodejs_compat" product="workers" />

## 3. Connect Hyperdrive to a database

Expand Down
20 changes: 3 additions & 17 deletions src/content/docs/workers/tutorials/postgres/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -58,17 +58,9 @@ cd postgres-tutorial

### Enable Node.js compatibility

<Render file="nodejs-compat-howto" />
[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";

<WranglerConfig>

```toml title="wrangler.toml"
compatibility_flags = ["nodejs_compat_v2"]
```

</WranglerConfig>
<Render file="nodejs_compat" product="workers" />

## 2. Add the PostgreSQL connection library

Expand Down Expand Up @@ -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/).



<WranglerConfig>

```toml
Expand All @@ -126,8 +116,6 @@ DB_URL="<ENTER YOUR POSTGRESQL CONNECTION STRING>"

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:



<WranglerConfig>

```toml
Expand Down Expand Up @@ -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.



<WranglerConfig>

```toml {7-9}
Expand Down
Loading