Skip to content

[hyperdrive] Update Get Started to use pg #22982

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

Merged
merged 1 commit into from
Jun 10, 2025
Merged

[hyperdrive] Update Get Started to use pg #22982

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
14 changes: 7 additions & 7 deletions src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,8 @@ Hyperdrive uses Workers [TCP socket support](/workers/runtime-apis/tcp-sockets/#

| Driver | Documentation | Minimum Version Required | Notes |
| ---------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| node-postgres - `pg` (recommended) | [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. |
| Postgres.js | [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. |
Expand All @@ -68,18 +68,18 @@ The following examples show you how to:
2. Pass the Hyperdrive connection string and connect to the database.
3. Query your database via Hyperdrive.

### Postgres.js

The following Workers code shows you how to use [Postgres.js](https://github.com/porsager/postgres) with Hyperdrive.

<Render file="use-postgres-js-to-make-query" product="hyperdrive" />

### node-postgres / pg

Install the `node-postgres` driver:

<Render file="use-node-postgres-to-make-query" product="hyperdrive" />

### Postgres.js

The following Workers code shows you how to use [Postgres.js](https://github.com/porsager/postgres) with Hyperdrive.

<Render file="use-postgres-js-to-make-query" product="hyperdrive" />

## Identify connections from Hyperdrive

To identify active connections to your Postgres database server from Hyperdrive:
Expand Down
39 changes: 20 additions & 19 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 @@ -182,11 +182,15 @@ Once you have created a Hyperdrive configuration and bound it to your Worker, yo
<Tabs>
<TabItem label="PostgreSQL">

To connect to your database, you will need a database driver which allows you to authenticate and query your database. For this tutorial, you will use [Postgres.js](https://github.com/porsager/postgres), one of the most widely used PostgreSQL drivers.
To connect to your database, you will need a database driver which allows you to authenticate and query your database. For this tutorial, you will use [node-postgres (pg)](https://node-postgres.com/), one of the most widely used PostgreSQL drivers.

To install `postgres`, ensure you are in the `hyperdrive-tutorial` directory. Open your terminal and run the following command:
To install `pg`, ensure you are in the `hyperdrive-tutorial` directory. Open your terminal and run the following command:

<PackageManagers pkg="postgres" comment="This should install v3.4.5 or later" />
<PackageManagers pkg="pg" comment="This should install v8.13.0 or later" />

If you are using TypeScript, you should also install the type definitions for `pg`:

<PackageManagers pkg="@types/pg" dev comment="This should install v8.13.0 or later" />

With the driver installed, you can now create a Worker script that queries your database.

Expand Down Expand Up @@ -217,8 +221,8 @@ The `index.ts` file is where you configure your Worker's interactions with Hyper
Populate your `index.ts` file with the following code:

```typescript
// Postgres.js 3.4.5 or later is recommended
import postgres from "postgres";
// pg 8.13.0 or later is recommended
import { Client } from "pg";

export interface Env {
// If you set another name in the Wrangler config file as the value for 'binding',
Expand All @@ -228,27 +232,24 @@ export interface Env {

export default {
async fetch(request, env, ctx): Promise<Response> {
// Create a connection using the Postgres.js driver (or any supported driver, ORM or query builder)
// with the Hyperdrive credentials. These credentials are only accessible from your Worker.
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 not using array types in your Postgres schema,
// disabling this will save you an extra round-trip every time you connect.
fetch_types: false,
});
// Create a client using the pg driver (or any supported driver, ORM or query builder)
// with the Hyperdrive credentials. These credentials are only accessible from your Worker.
const sql = new Client({
connectionString: env.HYPERDRIVE.connectionString,
});

try {
// Connect to the database
await sql.connect();

// Sample query
const results = await sql`SELECT * FROM pg_tables`;
const results = await sql.query(`SELECT * FROM pg_tables`);

// Clean up the client after the response is returned, before the Worker is killed
ctx.waitUntil(sql.end());

// Return result rows as JSON
return Response.json(results);
return Response.json(results.rows);
} catch (e) {
console.error(e);
return Response.json(
Expand All @@ -263,7 +264,7 @@ export default {
Upon receiving a request, the code above does the following:

1. Creates a new database client configured to connect to your database via Hyperdrive, using the Hyperdrive connection string.
2. Initiates a query via `await sql` that outputs all tables (user and system created) in the database (as an example query).
2. Initiates a query via `await sql.query()` that outputs all tables (user and system created) in the database (as an example query).
3. Returns the response as JSON to the client.

</TabItem>
Expand Down