Connect Vercel and Neon manually

This guide describes how to manually connect a Vercel project to a Neon database.

note

Alternatively, you can connect using the Neon Vercel Integration, which automatically creates a branch for each preview deployment. For more information, see Connect with the Neon Vercel Integration.

Prerequisites

A Neon project. If you do not have one, see Set up a project.
A Vercel account.
A project deployed to Vercel. If you do not have one, see Creating a project, in the Vercel documentation.

Gather your Neon connection details

You can gather most of these details from the Connection Details widget on the Neon Dashboard. Select a branch, a role, and the database you want to connect to. A connection string is constructed for you.

Connection details widget

The connection string includes the role name, hostname, and database name. For example:

postgres://sally:<password>@ep-cold-poetry-404091.us-east-2.aws.neon.tech/neondb
             ^                              ^                                ^
             |- <role name>                 |- <hostname>                    |- <database name>

role name: sally
hostname: ep-cold-poetry-404091.us-east-2.aws.neon.tech
database name: neondb

The password is only included in the connection string when the project is first created or after resetting a the password. If you misplaced your password, you can reset it by selecting the Reset Password link on the Connection Details widget or by navigating to the Roles page.

Configure project environment variables in Vercel

The environment variables required to connect your application to Neon depend on your application. Some applications use a DATABASE_URL environment variable with a database connection string:

DATABASE_URL="sally:<password>@ep-cold-poetry-404091.us-east-2.aws.neon.tech/neondb"

Other applications may use PG* environment variables to define database connection details:

PGHOST=ep-cold-poetry-404091.us-east-2.aws.neon.tech
PGUSER=sally
PGDATABASE=neondb
PGPASSWORD=<password>
PGPORT=5432

note

Neon uses the default PostgreSQL port, 5432.

To configure the environment variables required by your application:

note

Vercel environment variables can also be configured when you first deploy an application to Vercel.

Navigate to the Vercel dashboard.
Select your Vercel project.
Select Settings.
Select Environment variables.
Enter the environment variable name in the Key field and add the value.
Click Add another if you need to add more variables.
Select the Vercel environments to which the variable(s) will apply (Production, Preview, Development)
Click Save.

Add Vercel environment variable settings

You must redeploy your application in Vercel for the environment variable settings to take effect.