Connecting with the Vercel-Managed Integration

About this integration

Vercel-Managed Integration (also known as Neon Postgres Native Integration) lets you add a Neon Postgres database to your Vercel project with billing handled entirely inside Vercel. Installing it:

• Creates a Neon account + project for you (if you don't already have one)
• For existing Neon users, adds a new organization named Vercel: <team-name> to your account
• Injects the required database environment variables (DATABASE_URL, etc.) into your Vercel project
• Optionally creates a dedicated database branch for every Preview Deployment so you can test schema changes safely

Installation walkthrough

1. Open Neon integration

   Open the Neon integration on the Vercel Marketplace and click Install.

2. Add the integration in Vercel

   This opens the Install Neon modal where you can choose between two options. Select Create New Neon Account, then click Continue.

   

3. Complete Vercel's configuration

   Accept the terms, pick a region & plan, then name your database. (Remember: a "Database" in Vercel is a Project in Neon.)

4. View storage settings

   After creation you'll land on Vercel's Storage tab that includes status, plan, connection string, billing plan, and more.

5. Optionally open the project in the Neon Console

   From the Storage tab, click Open in Neon to jump straight to your new Neon project dashboard in the Neon Console. You'll notice it lives in an organization named Vercel: <your-vercel-team>.

Connecting the database to a Vercel project

1. In Storage → <your database> → Connect Project choose the Vercel project and the environments that should receive database variables (Development, Preview, Production).

   

2. (Optional) Under Advanced Options → Deployments Configuration enable Preview to turn on Preview Branching (see next section).

   

3. Click Connect.

Enable automated preview branching (recommended)

Preview branching creates an isolated Neon branch (copy-on-write) for every Vercel Preview Deployment so database schema changes can be tested safely.

To enable:

1. While connecting the project (step above) toggle Required → Preview.
2. Make sure Resource must be active before deployment is also on. This allows Vercel to wait for the branch to be ready.

Once enabled, the flow looks like this:

1. Developer pushes to feature branch → Vercel kicks off Preview Deployment.

2. Vercel sends a webhook to Neon → Neon creates branch preview/<git-branch>.

3. Environment variables for the branch connection are injected via webhook at deployment time, overriding preview environment variables for this deployment only (cannot be accessed or viewed in your Vercel project's environment variable settings).

4. (Optional) Run migrations in build step so schema matches code.

   

Test the setup

To verify preview branching works:

1. Create a local branch: git checkout -b test-feature
2. Make any change and commit: git commit -a -m "Test change"
3. Push: git push
4. Check Vercel deployments and Neon Console branches to confirm the preview branch was created

Managing & billing

Because your database is managed by Vercel, you can only perform these action in the Vercel dashboard:

• Change plan, billing tier, or scale settings (compute size, autoscaling, scale-to-zero)
• View or modify database configuration via Storage → Settings → Change Configuration
• Monitor usage via Storage → Usage (also available in Neon Console)
• Create additional databases (each becomes a new Neon project)
• Rename or delete a database (deleting removes the underlying Neon project permanently)
• Manage members / collaborators (handled through Vercel "Members", not the Neon Console)
• Delete the Neon organization (only happens automatically if you uninstall the integration)
• Update connection-string environment variables (prefix changes, etc.)

Everything else (querying data, branching, monitoring usage) works exactly the same in the Neon Console.

Common operations

Add another database (project)

1. Go to Integrations → Neon Postgres → Manage → More Products → Install
2. Select region, scale settings, and plan
3. Specify a Database Name and click Create

Change compute / scale settings

Storage → Settings → Change Configuration lets you resize compute, adjust scale-to-zero, or switch Neon plan tiers. Changes apply to all databases in the installation.

Delete the database

Deleting from Vercel permanently removes the Neon project and all data. This cannot be undone. To delete:

1. Vercel Dashboard → Storage → Settings
2. Select your database
3. Find Delete Database section and confirm

Disconnect a project from database

To disconnect a Vercel project without deleting the database:

1. Go to Storage → <your database> → Projects
2. Select your project and choose Remove Project Connection

This removes database environment variables from your Vercel project but keeps the database intact. Previously created preview branches remain but new ones won't be created.

Manage branches created by the integration

Preview deployments create database branches that accumulate over time. Delete unused branches to avoid hitting storage limits and branch quotas. Delete branches via:

• Neon Console - Individual or bulk deletion
• Neon CLI - Command line management
• Neon API - Programmatic cleanup

Environment variables set by the integration

Neon Auth variables automatically sync user profiles to your database in the neon_auth.users_sync table, enabling authentication without additional setup. Learn more in the Neon Auth guide.

Limitations

• You cannot use this integration with the Neon-Managed integration in the same Vercel project
• Neon CLI access: Requires API key authentication (the neon auth command won't work since the account is Vercel-managed)
• Cannot install if you currently use Vercel Postgres (deprecated) - contact Vercel about transitioning
• Manual branch deletion required (unlike the Neon-Managed Integration which offers automatic cleanup)
• Preview deployment environment variables: Branch-specific connection variables cannot be accessed or viewed in your Vercel project's environment variable settings (they're injected at deployment time only and not stored to avoid manual cleanup when branches are deleted)