hyperdrive

Hyperdrive

Accelerate access to existing PostgreSQL and MySQL databases with connection pooling and caching.

FIRST: Create Hyperdrive Configuration

# Create a Hyperdrive configuration for your database
npx wrangler hyperdrive create <YOUR_CONFIG_NAME> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

# Copy the ID from the output for your wrangler.jsonc

Add the binding to wrangler.jsonc:

{
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<YOUR_DATABASE_ID>"
    }
  ]
}

When to Use

Use Hyperdrive when:

• Connecting to existing databases - PostgreSQL or MySQL hosted anywhere
• Reducing connection latency - Connection pooling eliminates per-request connection overhead
• Geographic distribution - Cache query results at the edge for read-heavy workloads
• Database migration - Connect Workers to traditional databases without rewriting apps
• Connection limits - Share connections across many Workers efficiently

Quick Reference

Operation	API
Get connection string	env.HYPERDRIVE.connectionString
Connect with Postgres.js	postgres(env.HYPERDRIVE.connectionString)
Query with Postgres.js	await sql`SELECT * FROM users`
No cleanup needed	Hyperdrive handles connection pooling—don't call sql.end()
List configs	npx wrangler hyperdrive list
Get config details	npx wrangler hyperdrive get <ID>
Update config	npx wrangler hyperdrive update <ID> --origin-password=<NEW_PASSWORD>
Delete config	npx wrangler hyperdrive delete <ID>

Connect with Postgres.js

Install dependencies first:

npm install postgres

Code:

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 your 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);

    try {
      // Test query
      const results = await sql`SELECT * FROM pg_tables`;

      // Return result rows as JSON
      return Response.json(results);
    } catch (e) {
      console.error(e);
      return Response.json(
        { error: e instanceof Error ? e.message : e },
        { status: 500 },
      );
    }
  },
} satisfies ExportedHandler<Env>;