Connect to Neon
Connect Hyperdrive to a Neon Postgres database.
This example shows you how to connect Hyperdrive to a Neon Postgres database.
You can connect Hyperdrive to any existing Neon database by creating a new user and fetching your database connection string.
- Go to the Neon dashboard and select the project (database) you wish to connect to.
- Select Roles from the sidebar and select New Role. Enter
hyperdrive-user
as the name (or your preferred name) and copy the password. Note that the password will not be displayed again: you will have to reset it if you do not save it somewhere. - Select Dashboard from the sidebar > go to the Connection Details pane > ensure you have selected the branch, database and role (for example,
hyperdrive-user
) that Hyperdrive will connect through. - Select the
psql
and check the pooled connection checkbox. Note down the connection string (starting withpostgres://hyperdrive-user@...
) from the text box.
With both the connection string and the password, you can now create a Hyperdrive database configuration.
To configure Hyperdrive, you will need:
- The IP address (or hostname) and port of your database.
- The database username (for example,
hyperdrive-demo
) you configured in a previous step. - The password associated with that username.
- The name of the database you want Hyperdrive to connect to. For example,
postgres
.
Hyperdrive accepts the combination of these parameters in the common connection string format used by database drivers:
postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name
Most database providers will provide a connection string you can directly copy-and-paste directly into Hyperdrive.
To create a Hyperdrive configuration with the Wrangler CLI, open your terminal and run the following command. Replace <NAME_OF_HYPERDRIVE_CONFIG> with a name for your Hyperdrive configuration and paste the connection string provided from your database host, or replace user
, password
, HOSTNAME_OR_IP_ADDRESS
, port
, and database_name
placeholders with those specific to your database:
npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"
This command outputs a binding for wrangler.toml
:
name = "hyperdrive-example"main = "src/index.ts"compatibility_date = "2023-09-11"
node_compat = true # required for database drivers to function
# Pasted from the output of `wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string=[...]` above.[[hyperdrive]]binding = "HYPERDRIVE"id = ""
Install the driver:
npm install pg
Copy the below Worker code, which passes the connection string generated from env.HYPERDRIVE.connectionString
directly to the driver.
import { Client } from "pg";
export interface Env { // If you set another name in wrangler.toml as the value for 'binding', // replace "HYPERDRIVE" with the variable name you defined. HYPERDRIVE: Hyperdrive;}
export default { async fetch(request, env, ctx): Promise<Response> { console.log(JSON.stringify(env)); // Create a database client that connects to our database via Hyperdrive // Hyperdrive generates a unique connection string you can pass to // supported drivers, including node-postgres, Postgres.js, and the many // ORMs and query builders that use these drivers. const client = new Client({ connectionString: env.HYPERDRIVE.connectionString, });
try { // Connect to our database await client.connect();
// Test query const result = await client.query({ text: "SELECT * FROM pg_tables" });
// Returns result rows as JSON return Response.json({ result: result }); } catch (e) { console.log(e); return Response.json({ error: e.message }, { status: 500 }); } },} satisfies ExportedHandler<Env>;
- Learn more about How Hyperdrive Works.
- Refer to the troubleshooting guide to debug common issues.
- Understand more about other storage options available to Cloudflare Workers.