Use Neon with Cloudflare Hyperdrive
Connect Cloudflare Hyperdrive to your Neon Postgres database for faster queries
Cloudflare Hyperdrive is a serverless application that proxies queries to your database and accelerates them. It works by maintaining a globally distributed pool of database connections, and routing queries to the closest available connection.
This is specifically useful for serverless applications that cannot maintain a persistent database connection and need to establish a new connection for each request. Hyperdrive can significantly reduce the latency of these queries for your application users.
This guide demonstrates how to configure a Hyperdrive service to connect to your Neon Postgres database. It demonstrates how to implement a regular Workers
application that connects to Neon directly and then replace that connection with a Hyperdrive
connection to achieve performance improvements.
Prerequisites
To follow along with this guide, you require:
-
A Neon account. If you do not have one, sign up at Neon. Your Neon project comes with a ready-to-use Postgres database named
neondb
. We'll use this database in the following examples. -
A Cloudflare account. If you do not have one, sign up for Cloudflare Workers to get started.
NOTE: You need to be on Cloudflare Workers' paid subscription plan to use Hyperdrive.
-
Node.js and npm installed on your local machine. We'll use Node.js to build and deploy our Workers application.
Setting up your Neon database
Initialize a new project
-
Log in to the Neon Console and navigate to the Projects section.
-
Click the New Project button to create a new project.
-
From your project dashboard, navigate to the SQL Editor from the sidebar, and run the following SQL command to create a new table in your database:
Next, we insert some sample data into the
books_to_read
table, so we can query it later:
Retrieve your Neon database connection string
Log in to the Neon Console and navigate to the Connection Details section to find your database connection string. It should look similar to this:
Keep your connection string handy for later use.
Setting up your Cloudflare Workers application
Create a new Worker project
Run the following command in a terminal window to set up a new Cloudflare Workers project:
This initiates an interactive CLI prompt to generate a new project. To follow along with this guide, you can use the following settings:
When asked if you want to deploy your application, select no
. We'll develop and test the application locally before deploying it to the Cloudflare Workers platform.
The create-cloudflare
CLI also installs the Wrangler
tool to manage the full workflow of testing and managing your Worker applications. To emulate the Node environment in the Workers runtime, we need to add the following entry to the wrangler.toml
file.
Implement the Worker script
We'll use the node-postgres
library to connect to the Postgres database (directly to Neon first, later we will connect to the Hyperdrive service), so you need to install it as a dependency. Navigate to the project directory and run the following command:
Now, you can update the src/index.js
file in the project directory with the following code:
The fetch
handler defined above gets called when the worker receives an HTTP request. It will query the Neon database to fetch the full list of books in our to-read list.
Test the worker application locally
First, you need to configure the DATABASE_URL
environment variable to point to the Neon database. You can do this by creating a .dev.vars
file at the root of the project directory with the following content:
Now, to test the worker application locally, you can use the wrangler
CLI which comes with the Cloudflare project setup.
This command starts a local server and simulates the Cloudflare Workers environment. You can visit the printed URL in your browser to test the worker application. It should return a JSON response with the list of books from the books_to_read
table.
Setting up Cloudflare Hyperdrive
With our Workers application able to query the Neon database, we will now set up Cloudflare Hyperdrive to connect to Neon and accelerate the database queries.
Create a new Hyperdrive service
You can use the Wrangler
CLI to create a new Hyperdrive service, using your Neon database connection string from earlier:
This command creates a new Hyperdrive service named neon-guide-drive
and outputs its configuration details. Copy the id
field from the output, which we will use next.
Bind the Worker project to Hyperdrive
Cloudflare workers uses Bindings
to interact with other resources on the Cloudflare platform. We will update the wrangler.toml
file in the project directory to bind our Worker project to the Hyperdrive service.
Add the following lines to the wrangler.toml
file. This lets us access the Hyperdrive service from our Worker application using the HYPERDRIVE
binding.
Update the Worker script to use Hyperdrive
Now, you can update the src/index.js
file in the project directory to query the Neon database, through the Hyperdrive service.
Deploy the updated Worker
Now that we have updated the Worker script to use the Hyperdrive service, we can deploy the updated Worker to the Cloudflare Workers platform:
This command uploads the updated Worker script to the Cloudflare Workers platform and makes it available at a public URL. You can visit the URL in your browser to test that the application works.
Removing the example application and Neon project
To delete your Worker project, you can use the Cloudflare dashboard or run wrangler delete
from your project directory, specifying your project name. Refer to the Wrangler documentation for more details.
To delete your Neon project, follow the steps outlined in the Neon documentation under Delete a project.
Example application
Resources
Need help?
Join our Discord Server to ask questions or see what others are doing with Neon. Users on paid plans can open a support ticket from the console. For more detail, see Getting Support.