Connecting with the Neon-Managed Integration

• The purpose of the Neon-Managed Integration
• How to install it from Connectable Accounts
• How automated Preview Branching works
• How to manage environment variables and branch cleanup

• Vercel-Managed Integration
• Manual Connections

The Neon-Managed Integration links your existing Neon project to a Vercel project while keeping billing in Neon. Instead of sharing a single database across all preview deployments, this integration creates an isolated database branch for each preview deployment.

Key features:

• One-click connection from Vercel Marketplace
• Automatic database branches for each preview deployment
• Environment variable injection (DATABASE_URL, DATABASE_URL_UNPOOLED, PG* variables)
• Automatic cleanup when branches are deleted

Choose the Neon-Managed Integration if you already have a Neon account/project or prefer to manage billing directly with Neon.

Before you begin, ensure you have:

• A Neon account with at least one project and database role
• A Vercel account with a project linked to GitHub, GitLab, or Bitbucket

Once connected successfully, you'll see:

In Neon Console:

• A vercel-dev branch (if enabled) under Branches
• Future preview branches will appear here automatically

In Vercel:

• DATABASE_URL and other environment variables under Settings → Environment Variables

The integration automatically creates isolated database environments for each preview deployment:

If you've enabled Managed Better Auth on your production branch, it's automatically provisioned on preview branches too. Preview deployments receive NEON_AUTH_BASE_URL and VITE_NEON_AUTH_URL environment variables, letting you test authentication in isolated environments. Auth data branches with your database, so each preview has its own independent user profiles and sessions.

This isolation allows you to test data and schema changes safely in each pull request. To apply schema changes automatically, add migration commands to your Vercel build configuration:

1. Go to Vercel Dashboard → Settings → Build and Deployment Settings

2. Enable Override and add your build commands, including migrations, for example:

   npx prisma generate && npx prisma migrate deploy && npm run build

This ensures schema changes in your commits are applied to each preview deployment's database branch.

The integration sets both modern (DATABASE_URL, DATABASE_URL_UNPOOLED) and legacy PostgreSQL variables (POSTGRES_URL, PGHOST, etc.) for Production and Development environments. Preview variables are injected dynamically per deployment.

• DATABASE_URL: Pooled connection (recommended for most applications)
• DATABASE_URL_UNPOOLED: Direct connection (for tools requiring direct database access)
• NEON_AUTH_BASE_URL, VITE_NEON_AUTH_URL: Managed Better Auth endpoints (automatically set when Managed Better Auth is enabled on production branch)

To customize which variables are used:

1. Go to Neon Console → Integrations → Manage → Settings
2. Select the variables you want (for example, PGHOST, PGUSER, etc.)
3. Click Save changes

When you rotate the selected role password in Neon, the integration automatically syncs updated credentials to Vercel environment variables for connected projects.

If deployments still use older credentials, open Neon Console → Integrations → Manage → Settings and click Save changes to force a resync.

Automatic cleanup (recommended): Enable Automatically delete obsolete Neon branches during setup to remove preview branches automatically when the corresponding Git branch is deleted. Cleanup runs the next time a preview deployment is created.

Unlike the Vercel-Managed Integration, this cleanup is not affected by Vercel's deployment retention policies. For a full comparison and additional cleanup options, see Managing Vercel preview branch cleanup.

Manual cleanup: If needed, you can delete branches manually:

• Individual branches: Neon Console → Integrations → Manage → Branches → trash icon
• Bulk delete: Use Delete all in the same interface
• API/CLI: Use Neon CLI or API for programmatic cleanup

• Don't rename branches: Renaming either the Git branch or Neon branch breaks name-matching logic and may cause unintended deletions
• Avoid child branches: Creating child branches on preview branches prevents automatic deletion
• Role dependency: The integration depends on the selected role; removing it will break the integration

To disconnect the integration: Neon Console → Integrations → Manage → Disconnect. This stops creating new preview branches but doesn't remove existing branches or the integration from Vercel.

• One-to-one relationship: Each Neon project connects to exactly one Vercel project
• Integration exclusivity: Cannot coexist with the Vercel-Managed Integration in the same Vercel project
• Role dependency: Integration requires the selected PostgreSQL role to remain active

0%

• Test preview branching

  Create a feature branch and push changes to verify preview deployments work correctly

• Configure build commands

  Add migration commands to Vercel's build settings if using an ORM like Prisma

• Set up branch cleanup

  Enable automatic cleanup or establish a manual cleanup process

• Customize environment variables

  Review and adjust which database variables are injected into your deployments

If you see "Failed to set environment variables" during setup, remove conflicting variables in Vercel first:

1. Go to Vercel → Settings → Environment Variables
2. Remove or rename existing DATABASE_URL, PGHOST, PGUSER, PGDATABASE, or PGPASSWORD variables
3. Retry the integration setup

Issue: Preview branches no longer created Cause: The PostgreSQL role selected during setup was deleted Solution: Reinstall the integration with a valid role, or change the role in Neon Console → Integrations → Manage → Settings

Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.