Use Neon with Cloudflare Workers
Connect a Neon Postgres database to your Cloudflare Workers application
Cloudflare Workers is a serverless platform allowing you to deploy your applications globally across Cloudflare's network. It supports running JavaScript, TypeScript, and WebAssembly, making it a great choice for high-performance, low-latency web applications.
This guide demonstrates how to connect to a Neon Postgres database from your Cloudflare Workers application. We'll use the Neon serverless driver to connect to the database and make queries.
Prerequisites
To follow along with this guide, you will need:
- 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.
- Node.js and npm installed on your local machine. We'll use Node.js to build and deploy the 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 the Neon Dashboard, navigate to the SQL Editor from the sidebar, and run the following SQL command to create a new table in your database:
Next, insert some sample data into the
books_to_read
table so that you 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. Select the Pooled connection option to add the -pooler
option to your connection string. A pooled connection is recommended for serverless environments. For more information, see Connection pooling.
Your pooled connection string should look similar to this:
Keep your connection string handy for later use.
Setting up your Cloudflare Workers project
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 Cloudflare Workers platform.
The create-cloudflare
CLI installs the Wrangler
tool to manage the full workflow of testing and managing your Worker applications.
Implement the Worker script
We'll use the Neon serverless driver to connect to the Neon database, so you need to install it as a dependency:
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
You first need to configure the DATABASE_URL
environment variable to point to our 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 http://localhost:8787
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.
Deploying your application with Cloudflare Workers
Authenticate Wrangler with your Cloudflare account
Run the following command to link the Wrangler tool to your Cloudflare account:
This command will open a browser window and prompt you to log into your Cloudflare account. After logging in and approving the access request for Wrangler
, you can close the browser window and return to your terminal.
Add your Neon connection string as a secret
Use Wrangler to add your Neon database connection string as a secret to your Worker:
When prompted, paste your Neon connection string.
Publish your Worker application and verify the deployment
Now, you can deploy your application to Cloudflare Workers by running the following command:
The Wrangler CLI will output the URL of your Worker hosted on the Cloudflare platform. Visit this URL in your browser or use curl
to verify the deployment works as expected.
Removing the example application and Neon project
To delete your Worker, 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.
Source code
You can find the source code for the application described in this guide on GitHub.
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.