Use Neon with Cloudflare Workers

Create a Hyperdrive user in Neon

To use Hyperdrive with Neon, you'll need to create a dedicated database role for Hyperdrive to use:

1. In the Neon Console, navigate to your project.
2. Select Branches from the sidebar, then select the branch you want to use.
3. Navigate to the Roles & Databases section.
4. Click New Role and enter hyperdrive-user as the name (or your preferred name).
5. Copy the password that is generated. You'll use this password in the connection string in the next step.

Get your Neon connection string for Hyperdrive

1. In the Neon Console, select Dashboard from the sidebar.

2. Go to the Connection Details pane.

3. Select the branch, database, and role (for example, hyperdrive-user) that Hyperdrive will connect through.

4. Select Connection String from the dropdown menu.

5. Important: Uncheck the Pooled connection checkbox. Hyperdrive manages connection pooling, so you need the direct connection string.

6. Copy the connection string, which should look like this:

   postgres://hyperdrive-user:PASSWORD@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname

Create a new Worker project

Run the following command in a terminal window to set up a new Cloudflare Workers project:

npm create cloudflare@latest

This initiates an interactive CLI prompt to generate a new project. To follow along with this guide, you can use the following settings:

├ In which directory do you want to create your application?
│ type my-neon-worker
│
├ What would you like to start with?
│ select "Hello World example"
│
├ Which template would you like to use?
│ select "Worker only"
│
├ Which language do you want to use?
│ select "TypeScript"
│
├ Do you want to use git for version control?
│ select "Yes"
│
├ Do you want to deploy your application?
│ select "No"

For the purpose of demonstration, we will use the Worker only template and will deploy the application later.

Navigate to your project directory:

cd my-neon-worker

Create a Hyperdrive configuration

If you are not already authenticated with your Cloudflare account, use the following command:

npx wrangler login

This command will open a browser window and prompt you to log into your Cloudflare account. After logging in, you can close the browser window and return to your terminal.

Now, create a Hyperdrive configuration with your Neon connection string:

npx wrangler hyperdrive create my-neon-hyperdrive --connection-string="postgres://USERNAME:PASSWORD@HOSTNAME:PORT/DATABASE"

Replace the placeholder values with your actual connection details from the previous step. You will then be prompted with "Would you like Wrangler to add it on your behalf?". Enter Y, and continue with the default name. This will add the required Hyperdrive configuration (bindings) to your project.

Install the node-postgres driver

For Hyperdrive, we'll use the native PostgreSQL driver node-postgres:

npm install pg
npm install -D @types/pg

Create types

To generate the types for your Hyperdrive binding, use the following command:

npm run cf-typegen

Configure wrangler.jsonc

Update your wrangler.jsonc to add the compatibility_flags binding. We will also update the Hyperdrive binding and add the localConnectionString. This will allow our locally running application to connect to the Neon database via Hyperdrive. The complete wrangler.jsonc file should be as follows:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-neon-worker",
  "main": "src/index.ts",
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "compatibility_date": "2025-09-27",
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<your-hyperdrive-id-here>",
      "localConnectionString": "postgres://USERNAME:PASSWORD@HOSTNAME:PORT/DATABASE"
    }
  ]
}

Replace the following placeholders:

• localConnectionString with your Neon connection string (the same one you used to create the Hyperdrive configuration). This is required for local development with wrangler dev.

Implement the Worker script

Update the src/index.ts file in your project directory with the following code:

import { Client } from 'pg';

export default {
  async fetch(request, env, ctx) {
    const client = new Client({
      connectionString: env.HYPERDRIVE.connectionString
    });

    await client.connect();
    const result = await client.query('SELECT * FROM books_to_read;');

    // Clean up the client connection in the background
    ctx.waitUntil(client.end());

    return Response.json(result.rows);
  },
} satisfies ExportedHandler<Env>;

The fetch handler uses the Hyperdrive binding to connect to your Neon database through Cloudflare's optimized connection pooling service.

Test the worker application locally

To test the worker application locally, run:

npm run dev

This command starts a local server and simulates the Cloudflare Workers environment.

❯ npm run dev

> my-neon-worker@0.0.0 dev
> wrangler dev


 ⛅️ wrangler 4.61.0
───────────────────
Your Worker has access to the following bindings:
Binding                                                Resource               Mode
env.HYPERDRIVE (YOUR_HYPERDRIVE_ID)      Hyperdrive Config      local

❓ Your types might be out of date. Re-run `wrangler types` to ensure your types are correct.
╭──────────────────────────────────────────────────────────────────────╮
│  [b] open a browser [d] open devtools [c] clear console [x] to exit  │
╰──────────────────────────────────────────────────────────────────────╯
⎔ Starting local server...
[wrangler:info] Ready on http://localhost:8787

Visit http://localhost:8787 in your browser to test the worker application. It should return a JSON response with the list of books from the books_to_read table.