Getting started (9)

Last updated Oct 21, 2026 Hyperdrive accelerates access to your existing databases from Cloudflare Workers, making even single-region databases feel globally distributed.

By maintaining a connection pool to your database within Cloudflare's network, Hyperdrive reduces seven round-trips to your database before you can even send a query: the TCP handshake (1x), TLS negotiation (3x), and database authentication (3x).

Hyperdrive understands the difference between read and write queries to your database, and caches the most common read queries, improving performance and reducing load on your origin database.

This guide will instruct you through:

  • Creating your first Hyperdrive configuration.
  • Creating a Cloudflare Worker and binding it to your Hyperdrive configuration.
  • Establishing a database connection from your Worker to a public database.

Note

Hyperdrive currently works with PostgreSQL, MySQL and many compatible databases. This includes CockroachDB and Materialize (which are PostgreSQL-compatible), Supabase, and PlanetScale.

Learn more about the databases that Hyperdrive supports.

Prerequisites

Before you begin, ensure you have completed the following:

  1. Sign up for a Cloudflare account ↗︎ if you have not already.
  2. Install Node.js ↗︎.

Use Vite+ ( vp env) ↗︎ to install and manage Node.js versions.

For supported Node.js versions, refer to the Wrangler system requirements. 3. Have a publicly accessible PostgreSQL or MySQL (or compatible) database. If your database is in a private network, refer to Connect to a private database using Workers VPC.

1. Log in

Before creating your Hyperdrive binding, log in with your Cloudflare account by running:

npx wrangler login

You will be directed to a web page asking you to log in to the Cloudflare dashboard. After you have logged in, you will be asked if Wrangler can make changes to your Cloudflare account. Scroll down and select Allow to continue.

2. Create a Worker

New to Workers?

Refer to How Workers works to learn about the Workers serverless execution model works. Go to the Workers Get started guide to set up your first Worker.

Create a new project named hyperdrive-tutorial by running:

npmyarnpnpm

npm create cloudflare@latest -- hyperdrive-tutorial

yarn create cloudflare hyperdrive-tutorial

pnpm create cloudflare@latest hyperdrive-tutorial

For setup, select the following options:

  • For What would you like to start with?, choose Hello World example.
  • For Which template would you like to use?, choose Worker only.
  • For Which language do you want to use?, choose TypeScript.
  • For Do you want to use git for version control?, choose Yes.
  • For Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?, choose Yes.
  • For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

This will create a new hyperdrive-tutorial directory. Your new hyperdrive-tutorial directory will include:

  • A "Hello World" Worker at src/index.ts.
  • A wrangler.jsonc configuration file. wrangler.jsonc is how your hyperdrive-tutorial Worker will connect to Hyperdrive.

Enable Node.js compatibility

Node.js compatibility is required for database drivers, and needs to be configured for your Workers project.

For compatibility dates of 2026-08-04 or later, Workers and Pages projects enable both nodejs_compat and nodejs_compat_v2 by default. Built-in runtime APIs and polyfills are available without additional configuration. These flags are not used for these compatibility dates. Existing projects do not need to remove them when updating their compatibility date.

If your compatibility date is before 2026-08-04, add the nodejs_compat compatibility flag to your Wrangler configuration file to opt in:

{
    "compatibility_flags": [
        "nodejs_compat"
    ]
}

compatibility_flags = [ "nodejs_compat" ]

To turn off Node.js compatibility completely for a compatibility date of 2026-08-04 or later, remove the positive flags if present. Then add both no_nodejs_compat and no_nodejs_compat_v2. For configuration examples, refer to the Node.js compatibility flag.

3. Connect Hyperdrive to a database

Hyperdrive works by connecting to your database, pooling database connections globally, and speeding up your database access through Cloudflare's network.

It will provide a secure connection string that is only accessible from your Worker which you can use to connect to your database through Hyperdrive. This means that you can use the Hyperdrive connection string with your existing drivers or ORM libraries without needing significant changes to your code.

To create your first Hyperdrive database configuration, change into the directory you just created for your Workers project:

cd hyperdrive-tutorial

To create your first Hyperdrive, you will need:

  • The IP address (or hostname) and port of your database.
  • The database username (for example, hyperdrive-demo).
  • The password associated with that username.
  • The name of the database you want Hyperdrive to connect to. For example, postgres or mysql.

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 copy-and-paste directly into Hyperdrive.

To create a Hyperdrive connection, run the wrangler command, replacing the placeholder values passed to the --connection-string flag with the values of your existing database:

npx wrangler hyperdrive create <YOUR_CONFIG_NAME> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

mysql://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

Most database providers will provide a connection string you can copy-and-paste directly into Hyperdrive.

To create a Hyperdrive connection, run the wrangler command, replacing the placeholder values passed to the --connection-string flag with the values of your existing database:

npx wrangler hyperdrive create <YOUR_CONFIG_NAME> --connection-string="mysql://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

Manage caching

By default, Hyperdrive caches eligible read query results. If you wish to disable caching, pass the flag --caching-disabled.

Alternatively, you can use the --max-age flag to specify the maximum duration (in seconds) for which items should persist in the cache, before they are evicted. Default value is 60 seconds.

Hyperdrive does not invalidate cached read results when your application writes to your database. If your application needs read-after-write consistency, use a separate cache-disabled Hyperdrive configuration for the reads that must return fresh data. Refer to Query caching for guidance and Hyperdrive Wrangler commands for command options.

If successful, the command will output your new Hyperdrive configuration:

{
    "hyperdrive": [
        {
            "binding": "HYPERDRIVE",
            "id": "<example id: 57b7076f58be42419276f058a8968187>"
        }
    ]
}

Copy the id field: you will use this in the next step to make Hyperdrive accessible from your Worker script.

Note

Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's troubleshooting documentation to debug possible causes.

4. Bind your Worker to Hyperdrive

You must create a binding in your Wrangler configuration file for your Worker to connect to your Hyperdrive configuration. Bindings allow your Workers to access resources, like Hyperdrive, on the Cloudflare developer platform.

To bind your Hyperdrive configuration to your Worker, add the following to the end of your Wrangler file:

{
    "hyperdrive": [
        {
            "binding": "HYPERDRIVE",
            "id": "<YOUR_DATABASE_ID>" // the ID associated with the Hyperdrive you just created
        }
    ]
}

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<YOUR_DATABASE_ID>"

Specifically:

  • The value (string) you set for the binding (binding name) will be used to reference this database in your Worker. In this tutorial, name your binding HYPERDRIVE.
  • The binding must be a valid JavaScript variable name ↗︎. For example, binding = "hyperdrive" or binding = "productionDB" would both be valid names for the binding.
  • Your binding is available in your Worker at env.<BINDING_NAME>.

If you wish to use a local database during development, you can add a localConnectionString to your Hyperdrive configuration with the connection string of your database:

{
    "hyperdrive": [
        {
            "binding": "HYPERDRIVE",
            "id": "<YOUR_DATABASE_ID>", // the ID associated with the Hyperdrive you just created
            "localConnectionString": "<LOCAL_DATABASE_CONNECTION_URI>"
        }
    ]
}

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<YOUR_DATABASE_ID>"
localConnectionString = "<LOCAL_DATABASE_CONNECTION_URI>"

Note

Learn more about setting up Hyperdrive for local development.

5. Run a query against your database

Once you have created a Hyperdrive configuration and bound it to your Worker, you can run a query against your database.

Install a database driver

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) ↗︎, one of the most widely used PostgreSQL drivers.