Use Neon with Cloudflare Pages
Connect a Neon Postgres database to your Cloudflare Pages web application
Cloudflare Pages
is a modern web application hosting platform that allows you to build, deploy, and scale your web applications. While it is typically used to host static websites, you can also use it to host interactive web applications by leveraging functions
to run server-side code. Internally, Cloudflare functions are powered by Cloudflare Workers
, a serverless platform that allows you to run JavaScript code on Cloudflare's edge network.
This guide demonstrates how to connect to a Neon Postgres database from your Cloudflare Pages application. We'll create a simple web application using React
that tracks our reading list using the database and provides a form to add new books to it.
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 Pages to get started.
- Node.js and npm installed on your local machine. We'll use Node.js to build and deploy our
Pages
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 Pages project
Create a new project
We will create a simple React application using the Vite bundler framework. Run the following command in a terminal window to set up a new Vite project:
This initiates an interactive CLI prompt to generate a new project. To follow along with this guide, you can use the following settings:
We set up a template React configured to be built using Vite.
Implement the application frontend
Navigate to the my-neon-page
directory and open the src/App.jsx
file. Replace the contents of this file with the following code:
The App
component fetches the list of books from the server and displays them. It also provides a form to add new books to the list. Cloudflare
Pages allows us to define the API endpoints as serverless functions, which we'll implement next.
Implement the serverless functions
We'll use the Neon serverless driver to connect to the Neon database, so we first need to install it as a dependency:
Next, we'll create two serverless functions for the application. In a Cloudflare Pages
project, these must be defined in the functions
directory at the root of the project. For further details, refer to the Cloudflare Pages - Functions documentation.
Function to fetch list of books from the database
Create a new file named functions/books/index.js
in the project directory with the following content:
This function fetches the list of books from the books_to_read
table in the database and returns it as a JSON response.
Function to add a new book to the database
Create another file named functions/books/add.js
in the project directory with the following content:
This function extracts the book details from the request body and inserts it into the books_to_read
table in the database. It returns a JSON response indicating the success or failure of the operation.
Test the application locally
Our application is now ready to be tested locally. However, we first need to configure the DATABASE_URL
environment variable to point to our Neon database.
We can do this by creating a .dev.vars
file at the root of the project directory with the following content:
Now, to test the Pages
application locally, we can use the wrangler
CLI tool used to manage Cloudflare projects. We can use it using the npx
command as:
This command starts a local server simulating the Cloudflare environment. The function endpoints are run by the Wrangler tool while requests to the root URL are proxied to the Vite development server.
Visit the printed localhost URL in your browser to interact with the application. You should see the list of books fetched from the database and a form to add new books.
Deploying your application with Cloudflare Pages
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.
Publish your Pages application and verify the deployment
Now, you can deploy your application to Cloudflare Pages
by running the following command:
Give a unique name to your Cloudflare Pages
project above. The Wrangler CLI will output the URL of your application hosted on the Cloudflare platform. Visit this URL in your browser to interact with it.
Add your Neon connection string as an environment variable
The Cloudflare production deployment doesn't have access to the DATABASE_URL
environment variable yet. Hence, we need to navigate to the Cloudflare dashboard and add it manually.
Navigate to the dashboard and select the Settings
section in your project. Go to the Environment Variables tab and add a new environment variable named DATABASE_URL
with the value of your Neon database connection string.
To make sure the environment variable is available to the serverless functions, go back to the terminal and redeploy the project using the wrangler
CLI:
Now, visit the URL of your Cloudflare Pages
application to interact with it. You should see the list of books fetched from the Neon database and a form to add new books.
Removing the example application and Neon project
To delete your Cloudflare Pages
application, you can use the Cloudflare dashboard. Refer to the Pages 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.