Connect to pgEdge Cloud
Connect Hyperdrive to a pgEdge Postgres database.
This example shows you how to connect Hyperdrive to a pgEdge ↗ Postgres database. pgEdge Cloud provides easy deployment of fully-managed, fully-distributed, and secure Postgres.
You can connect Hyperdrive to any existing pgEdge database with the default user and password provided by pgEdge.
To retrieve your connection string from the pgEdge dashboard:
- Go to the pgEdge dashboard ↗ and select the database you wish to connect to.
- From the Connect to your database section, note down the connection string (starting with
postgres://app@...
) from the Connection String text box.
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 the Wrangler configuration file:
{ "name": "hyperdrive-example", "main": "src/index.ts", "compatibility_date": "2024-08-21", "compatibility_flags": [ "nodejs_compat" ], "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>" } ]}
name = "hyperdrive-example"main = "src/index.ts"compatibility_date = "2024-08-21"compatibility_flags = ["nodejs_compat"]
# Pasted from the output of `wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string=[...]` above.[[hyperdrive]]binding = "HYPERDRIVE"id = "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"
Install the driver:
npm install postgres
Copy the below Worker code, which passes the connection string generated from env.HYPERDRIVE.connectionString
directly to the driver.
import postgres from "postgres";
export interface Env { // If you set another name in the Wrangler config file as the value for 'binding', // replace "HYPERDRIVE" with the variable name you defined. HYPERDRIVE: Hyperdrive;}
export default { async fetch(request, env, ctx): Promise<Response> { // 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 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 using array types in your Postgres schema, it is necessary to fetch // type information to correctly de/serialize them. However, if you are not using // those, disabling this will save you an extra round-trip every time you connect. fetch_types: false, }, );
try { // Test query const result = await sql`SELECT * FROM pg_tables;`;
// Returns result rows as JSON return Response.json({ result: result }); } catch (e: any) { 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.