Get started

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 can cache 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.

​​ Prerequisites

To continue, you will need:

1. A Cloudflare account Open external link if you do not have one already.
2. npm Open external link installed on your local machine.
3. Node.js Open external link installed. Use a Node version manager like Volta Open external link or nvm Open external link to avoid permission issues and change Node.js versions. Wrangler requires a Node version of 16.17.0 or later.
4. A publicly accessible PostgreSQL (or PostgreSQL compatible) database. Cloudflare recommends Neon Open external link if you do not have an existing database. Read the Neon documentation to create your first database Open external link .

​​ 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

Create a new project named hyperdrive-tutorial by running:

$ npm create cloudflare@latest hyperdrive-tutorial

When setting up your hyperdrive-tutorial Worker, answering the questions as below:

1. Choose "Hello World" Worker for the type of application.
2. Select yes to using TypeScript.
3. Select yes to using Git.
4. Select no to 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.toml configuration file. wrangler.toml is how your hyperdrive-tutorial Worker will connect to Hyperdrive.

​​ Enable Node.js compatibility

To enable Node.js compatibility, add the nodejs_compat compatibility flag in your wrangler.toml configuration:

wrangler.toml
compatibility_flags = [ "nodejs_compat" ]

​​ 3. Connect Hyperdrive to a database

Hyperdrive works by connecting to your database.

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) 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 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 $NAME --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

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

{
  "id": "<example id: 57b7076f58be42419276f058a8968187>",
  "name": "your-config-name",
  "origin": {
    "host": "YOUR_DATABASE_HOST",
    "port": 5432,
    "database": "DATABASE",
    "user": "DATABASE_USER"
  },
  "caching": {
    "disabled": false
  }
}

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

​​ 4. Bind your Worker to Hyperdrive

You must create a binding for your Worker to connect to your Hyperdrive configuration. Bindings allow your Workers to access resources, like D1, on the Cloudflare developer platform. You create bindings by updating your wrangler.toml file.

To bind your Hyperdrive configuration to your Worker, add the following to the end of your wrangler.toml file:

wrangler.toml
compatibility_flags = [ "nodejs_compat" ] # required for database drivers to function

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "a76a99bc342644deb02c38d66082262a" # the ID associated with the Hyperdrive you just created

Specifically:

• The value (string) you set for the name (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 Open external link . 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>.

​​ 5. 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 Postgres.js Open external link , one of the most widely used PostgreSQL drivers.

To install postgres, ensure you are in the hyperdrive-tutorial directory. Open your terminal and run the following command:

$ npm i postgres
# This should install v3.4.5 or later.

With the driver installed, you can now create a Worker script that queries your database.

​​ Write a Worker

After you have set up your database, you will run a SQL query from within your Worker.

Go to your hyperdrive-tutorial Worker and open the index.ts file. The index.ts file is where you configure your Worker’s interactions with D1.

Populate your index.ts file with the following code:

src/index.ts
// Postgres.js 3.4.5 or later is recommended
import postgres from 'postgres'

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 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.log(e);
			return Response.json({ error: e.message }, { status: 500 });
		}
	},
} satisfies ExportedHandler<Env>;

In the code above, you have:

1. Created a new database client configured to connect to your database via Hyperdrive, using the Hyperdrive connection string.
2. Initiated a query via await sql that outputs all tables (user and system created) in the database (as an example query).
3. Returned the response as JSON to the client.

​​ 6. Deploy your database

You can now deploy your Worker to make your project accessible on the Internet. To deploy your Worker, run:

$ npx wrangler deploy
# Outputs: https://hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev

You can now visit the URL for your newly created project to query your live database.

For example, if the URL of your new Worker is hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev, accessing https://hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev/ will send a request to your Worker that queries your database directly.

By finishing this tutorial, you have created a Hyperdrive configuration, a Worker to access that database and deployed your project globally.

​​ Next steps

• Learn more about how Hyperdrive works.
• How to configure query caching.
• Troubleshooting common issues when connecting a database to Hyperdrive.

If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the Cloudflare Developers community on Discord Open external link .