Connect with the Neon Vercel Integration
Learn how to connect your Vercel project to Neon using the Neon Vercel Integration
This guide describes how to connect using the Neon Vercel Integration from the Vercel marketplace. The integration connects your Vercel project to a Neon database and enables creating a database branch for each preview deployment.
note
This is a Beta version of the Neon Vercel Integration. For assistance or to suggest improvements, please reach out to us on our Discord Server.
About the Neon Vercel Integration
Vercel preview deployments enable teams to collaborate effectively by automatically creating an isolated, production-like environment for every commit. This allows changes to be previewed before they are merged into production.
However, when databases are involved, teams often use a single database containing dummy data for all preview deployments. This setup is not ideal for these reasons:
- If the shared database encounters an issue, so will all preview deployments.
- Changes to the shared database schema might break all previously created preview deployments, making it a productivity bottleneck.
Neon’s branching feature addresses these challenges. A branch is a copy-on-write clone of your data, so creating it only takes a few seconds. This makes it a scalable and cost-effective solution for preview deployments, enabling you to create a branch for each pull request.
When you push changes to the repository associated with your Vercel project, triggering a preview deployment, the integration automatically creates a branch in Neon and connects it to your preview deployment by setting Vercel preview environment variables.
Add the Neon Vercel Integration
This section describes how to add the Neon Vercel Integration to your Vercel project.
Notes
- Please be aware that the Neon Vercel Integration connects one Vercel project to one Neon project. It does not support connecting multiple Vercel projects to one Neon project or connecting multiple Neon projects to one Vercel project.
- The Neon Vercel Integration is supported with GitHub, GitLab, and Bitbucket source code repositories.
Prerequisites:
- A Vercel account.
- A Vercel project. If you do not have one, see Creating a project, in the Vercel documentation.
- The integration initially sets the
DATABASE_URL
environment variable for your Vercel Production and Development environments. When you create a preview deployment, the integration will also set this variable for your Preview environment. Make sure this variable does not already exist in your Vercel project settings. To use different Postgres variables with the Neon integration, see Manage Vercel environment variables.
To add the integration:
- Navigate to the Neon Vercel Integration page, and click Add integration.
- Select a Vercel Account to add the integration to.
- Select the Vercel projects to add the integration to. You can select All Projects or Specific Projects but be aware that you can only connect one Vercel project to one Neon project and vice versa. By selecting All projects, you are simply making the integration available to use with all of your Vercel projects.
- Review the permissions required by the integration, and click Add Integration.
- In the Integrate Neon dialog:
-
Select a Vercel project.
-
Select the Neon project that you want to connect to your Vercel project by selecting the Neon project, database, and role that Vercel will use to connect.
The Create a branch for your development environment option creates a branch named
vercel-dev
and sets Vercel development environment variables for it. Thevercel-dev
branch is a clone of your project's primary branch (main
) that you can modify without affecting data on your primary branch.note
Branches created for preview deployments are created from the primary branch of your Neon project. Earlier versions of the integration created branches from the initial root branch of your Neon project, which is designated as the primary branch by default. Neon lets you change the primary branch. If you have an older version of the integration that creates branches from your project's root branch, and you want branches created from your primary branch instead, you can upgrade your integration by reinstalling it from the Vercel Marketplace.
When you finish making selections, click Continue.
-
Confirm the integration settings. This allows the integration to:
- Set environment variables for your Vercel project's production, development, and preview environments.
- Create database branches for preview deployments.
- Create a development branch for your Vercel development environment.
-
Click Connect to confirm and proceed with the integration. If you encounter a connection error, see Troubleshoot connection issues.
After the settings are configured, you are presented with a Success! dialog.
-
Click Done to complete the installation.
-
- To view the results of the integration in Neon:
- Navigate to the Neon Console.
- Select the project you are connected to.
- Select Branches.
You will see the primary branch of your project (
main
). If you created a development branch, you will also see avercel-dev
branch.
- To view the results of the integration in Vercel:
- Navigate to Vercel.
- Select the Vercel project you added the integration to.
- Select Settings > Environment Variables.
You should see the
DATABASE_URL
variable settings added by the integration.
Use the Neon Vercel Integration
After you add the Neon Vercel Integration to a Vercel project, Neon creates a database branch for each preview deployment. The branch is created when you push commits made on your local branch to your application's source code repository. To see the integration in action, follow these steps:
-
Create a branch in your local source code repository.
-
Make changes to your application on the local branch.
-
Commit the changes. For example:
-
Push your commit to the remote repository:
Pushing the commit triggers the following actions:
- The commit triggers a preview deployment in Vercel, as would occur without the Neon integration.
- The integration creates a branch in Neon. This branch is an isolated copy-on-write clone of your root branch, with its own dedicated compute endpoint. The branch is created with the same name as your
git
branch. - The integration sets Vercel preview environment variables to connect the preview deployment to the new branch.
note
The Neon Free Tier lets you create up to 10 branches. To avoid running out of branches for new preview deployments, remove old branches regularly. See Delete a branch for instructions.
Manage Vercel environment variables
The Neon Vercel Integration initially sets the DATABASE_URL
environment variable for your Vercel Production and Development environments. When you create a preview deployment, the integration also sets this variable for your Preview environment. If you want to use different Postgres environment variables, the Neon Vercel Integration also supports these variables for defining your database connection:
PGHOST
PGUSER
PGDATABASE
PGPASSWORD
You can enable these variables from the Neon Console:
- In the Neon Console, select your project.
- Select the Integrations page.
- Find the Vercel integration under the Manage heading, and click Manage.
- In the Vercel integration drawer, select the environment variables you require. The selected variables will be set in your Vercel project with your next push.
Notes
- Clicking Redeploy in Vercel does not apply variable changes made in Neon to your Vercel project. This only occurs with your next push.
- The integration appends the
sslmode=require
option to the Neon connection string that it sets for theDATABASE_URL
environment variable in Vercel.
Make the integration available to other Vercel projects
If you added the Neon Vercel Integration to a single Vercel project but would like to make it available for use with your other Vercel projects, complete the steps outlined below.
important
Please be aware that the Neon Vercel Integration connects one Vercel project to one Neon project. It does not support connecting multiple Vercel projects to one Neon project, nor does it support connecting multiple Neon projects to one Vercel project. The steps below outline how to make the integration available to other Vercel projects to use with their own separate and dedicated Neon project.
- Make sure the Neon Vercel Integration that you added previously has access to the Vercel project that you want to use with the Neon Vercel Integration.
- On the Vercel Dashboard, select Integrations.
- Find the Neon Postgres integration, and select Manage.
- On the Neon Postgres integration page, select Manage Access.
- On the Manage Access for Neon Postgres modal, make sure that the Neon Postgres integration has access to the Vercel project. You can do so by selecting Specific Projects and choosing a Vercel project, or by granting access to All Projects. If you previously granted access to All Projects, no change is necessary.
- Click Save.
- Navigate to this URL: https://vercel.com/integrations/neon/new.
- Follow the prompts. When you reach the Integrate Neon dialog, select the Vercel project that you want to add the integration to. Vercel projects that are already integrated with Neon are identified as
CONNECTED
, so you'll have to select a different Vercel project. - Continue following the prompts to complete the setup. These are the same steps described above, in Add the Neon integration. When you select a Neon project to connect to, be sure to select one that is not already connected to a Vercel project, as you cannot connect one Vercel project to multiple Neon projects or vice versa.
Troubleshoot connection issues
This section describes commonly encountered connection issues for the Neon Vercel Integration.
Failed to set environment variables
If the environment variables configured by the Neon integration already exist, you may encounter the following error due to an existing integration that sets one or more of the same environment variables.
In this case, you can remove or rename the existing environment variables in your Vercel project settings and retry the Neon integration.
-
From the Vercel project page, select Settings.
-
Locate the environment variables required by the Neon integration and remove or rename them.
note
Alternatively, you can remove the conflicting integration, assuming it is no longer required. This may be a previous Neon integration or another integration. Removing the integration removes the variables set by the integration.
-
Try adding the Neon integration again. See Add the Neon Vercel Integration.
DATABASE_URL not set on first preview deployment
In earlier versions of the integration, the preview environment DATABASE_URL
is not set by the Neon Vercel Integration on the first preview deployment after adding the integration to a Vercel project.
To avoid this issue, you can reinstall the integration to update to the latest version. Alternatively, a workaround is to redeploy your preview deployment in Vercel. The preview environment DATABASE_URL
is set on the next deployment. For redeploy instructions, see Managing Deployments, in the Vercel documentation.
Manage the Neon Postgres integration in Vercel
To view permissions, manage which Vercel projects your integration has access to, or uninstall the Neon integration:
-
On the Vercel dashboard, select Settings > Integrations.
-
Find the Neon integration and select Configure.
note
Removing the Neon Vercel Integration removes the Vercel environment variables set by the integration. It does not remove Neon branches created by the integration. To remove Neon branches, see Delete a branch.
Need help?
Join our Discord Server to ask questions or see what others are doing with Neon. Neon Pro Plan users can open a support ticket from the console. For more detail, see Getting Support.
Last updated on